Components menu
  2. components
  3. forms
  4. select

Select

Select lets merchants choose one option from an options menu. Consider select when you have 4 or more options, to avoid cluttering the interface.

Examples

Presents a classic dropdown menu or equivalent picker as determined by merchants’ browsers.

Drag to resize example

Props

disabled
boolean
Disable input
error
string | ReactElement | (string | ReactElement)[] | boolean
Display an error state
groups
(string | StrictOption | SelectGroup)[]
helpText
React.ReactNode
Additional text to aide in use
id
string
ID for form input
labelRequired
string
Label for the select
labelAction
Action
Adds an action to the label
labelHidden
boolean
Visually hide the label
labelInline
boolean
Show the label to the left of the value, inside the control
name
string
Name for form input
options
(string | StrictOption | SelectGroup)[]
List of options or option groups to choose from
placeholder
string
Example text to display as placeholder
value
string
Value for form input
onBlur
() => void
Callback when focus is removed
onChange
(selected: string, id: string) => void
Callback when selection is changed
onFocus
() => void
Callback when select is focussed

Default select

The Android menu is similar in behavior to the web dropdown.

Android select, and select with option menu

Disabled select

Use for selections that aren’t currently available. The surrounding interface should make it clear why the select box is disabled and how to activate it.

Disabled select component on Android

Default select

The iOS picker expands in-line. Merchants scroll to select the item they want.

iOS select, and select with option menu

Disabled select

Use for selections that aren’t currently available. The surrounding interface should make it clear why the select box is disabled and how to activate it.

Disabled select component on iOS

Best practices

The select component should:

  • Be used for selecting between 4 or more pre-defined options
  • Have a default option selected whenever possible
  • Use “Select” as a placeholder option only if there’s no logical default option

Content guidelines

Select label

Labels should:

  • Give a short description (1–3 words) of the requested input.
  • Be written in sentence case (the first word capitalized, the rest lowercase).
  • Avoid punctuation and articles (“the”, “an”, “a”).
  • Be independent sentences. To support internationalization, they should not act as the first part of a sentence that is finished by the component’s options.
  • Be descriptive, not instructional. If the selection needs more explanation, use help text below the field.

  • Email address

  • What is your email address?

  • Phone number

  • My phone number is:

Select options

Options should:

  • Use “Select” as the text for a placeholder option, if present
  • Be listed alphabetically or in another logical order so merchants can easily find the option they need
  • Be written in sentence case (the first word capitalized, the rest lowercase) and avoid using commas or semicolons at the end of each option
  • Be clearly labelled based on what the option will do