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

also known as Picklist, Picker

Figma:

Web:

iOS:

Android:

Props

Component props
Name
Type
Default
children
Required
React.Node
-

One or more SelectList.Option components, which may be grouped using SelectList.Group.

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.

disabled
boolean
-

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"
-

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: 40px, lg: 48px. See the size variant to learn more.

value
?string
-

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

Subcomponents

SelectList.Option

Use SelectList.Option to define the available options within SelectList.

SelectList.Option Props

SelectList.Option subcomponent props
Name
Type
Default
label
Required
string
-

The visible label for the option. Don't forget to localize!

value
Required
string
-

The underlying value of the option.

disabled
boolean
-

Used to disable the option.

SelectList.Group

Use SelectList.Group to group a subset of the options within SelectList.

SelectList.Group Props

SelectList.Group subcomponent props
Name
Type
Default
children
Required
React.Node
-

One or more SelectList.Option components.

label
Required
string
-

The label for the group. Don't forget to localize!

disabled
boolean
-

Used to disable the entire group of options.

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 RadioGroup 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.

Groups

SelectList.Group can be used to group related options. Note that disabling a group disables all of its options.

Component quality checklist

Component quality checklist
Quality item
Status
Status description
Figma Library
Ready
Component is available in Figma across all platforms.
Responsive Web
Ready
Component is available in code for web and mobile web.
iOS
Component is not currently available in code for iOS.
Android
Component is not currently available in code for Android.

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.

RadioGroup
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.