SelectList

View source on GitHub

SelectList displays a list of actions or options using the browser’s native select.

Props

Component props
Name
Type
Default
id
Required
string
-

A unique identifier to connect the underlying <select> with the associated label.

onChange
Required
({| event: SyntheticInputEvent<HTMLSelectElement>, value: string |}) => void
-

Callback triggered when the user selects a new option. See the controlled component variant to learn more.

options
Required
$ReadOnlyArray<{| label: string, value: string, disabled?: boolean |}>
-

The options displayed in the dropdown list. Note that disabled here is used to disable a single option. Be sure to localize the label.

disabled
boolean
false

Used to disable the entire SelectList.

errorMessage
string
-

Used to communicate error information to the user. Be sure to localize the text. See the error message variant to learn more.

helperText
string
-

Used to provide more information about the form field. Be sure to localize the text. See the helper text variant to learn more.

label
string
-

The label shown above the input. Be sure to localize the label.

labelDisplay
"visible" | "hidden"
"visible"

Whether the legend should be visible or not. If hidden, the legend is still available for screen reader users, but does not appear visually. See the label visibility variant for more info.

name
string
-

Used to specify the name of the control.

placeholder
string
-

If not provided, the first item in the list will be shown. Be sure to localize the text. See the controlled component variant to learn more.

size
"md" | "lg"
"md"

md: 40px, lg: 48px. See the size variant to learn more.

value
?string
-

The currently-selected value. See the controlled component variant to learn more.

Usage guidelines

When to use
  • When presenting users with a list of options that utilizes the native select functionality of the browser or device.
  • When presenting users with a list of options to choose from, like display settings.
When not to use
  • When more than 10 options are presented and the ability to filter the list would be beneficial. Use ComboBox instead.
  • When extra functionality, like groups, subtext or badges, is needed. Use Dropdown instead.
  • When the options are links and navigate users to different places. Use Dropdown instead.

Best practices

Do

Use SelectList when the user needs to select from a simple list of items.

Don't

Use SelectList when additional functionality such as subtext or images are needed. Use Dropdown instead.

Do

Order the list items in SelectList either alphabetically or by usage.

Don't

Use SelectList if there are fewer than 4 items in the list and there is space to display all options. Use RadioButton instead.

Do

Keep the same type of selection for a group of items. An example of this might be a filter bar. If some items could use SelectList and some items need to use Dropdown, use Dropdown for all the items in the group.

Don't

Mix Dropdown and SelectList in a group of items.

Accessibility

Labels

SelectList comes with Label built-in: just use the label prop. We strongly encourage always supplying a label. Be sure to provide a unique id so the Label is associated with the correct SelectList.

If SelectList is labeled by content elsewhere on the page, or a more complex label is needed, the labelDisplay prop can be used to visually hide the label. In this case, it is still available to screen reader users, but will not appear visually on the screen.

Variants

Size

Large

Use lg as the recommended size within Pinterest products.

Medium

Use md on denser surfaces, such as Business products or internal tools.

Label visibility

In some cases, the label for a SelectList is represented in a different way visually, as demonstrated below. In these instances, you can set labelDisplay="hidden" to ensure SelectList is properly labeled for screen readers while using a different element to represent the label visually.

Helper text

Helper text should be used when additional description may be required to understand the SelectList. Common examples include text that is legally required to be displayed, or instructions to fill out a form (e.g. proper formatting). If the text is optional, Tooltip could be used instead.

Controlled component

SelectList must be used as a controlled component when the placeholder or value props are needed. When used in this manner, onChange and value are required, while placeholder is optional.

Error message

errorMessage should be used to denote an error state in SelectList and to provide a message for how the user can fix it.

Dropdown
If additional functionality is needed in the menu, such as subtext, headers or custom styling, use Dropdown.

ComboBox
If users need the ability to choose an option by entering text to filter a long list of options, use ComboBox.

RadioButton
If users need the ability to choose between fewer than 4 options, use RadioButton.

Checkbox
If users need the ability to choose between a yes/no option, use Checkbox.

Edit page on GitHub