SelectList displays a list of actions or options using the browser’s native select.
also known as Picklist, Picker
Use SelectList.Option to define the available options within SelectList.
Use SelectList.Group to group a subset of the options within SelectList.
- 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.
Use SelectList when the user needs to select from a simple list of items.
Use SelectList when additional functionality such as subtext or images are needed. Use Dropdown instead.
Order the list items in SelectList either alphabetically or by usage.
Use SelectList if there are fewer than 4 items in the list and there is space to display all options. Use RadioGroup instead.
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.
lg as the recommended size within Pinterest products.
md on denser surfaces, such as business products or internal tools.
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 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.
SelectList must be used as a controlled component when the
value props are needed. When used in this manner,
value are required, while
placeholder is optional.
errorMessage should be used to denote an error state in SelectList and to provide a message for how the user can fix it.
SelectList.Group can be used to group related options. Note that disabling a group disables all of its options.
Component quality checklist
Component is available in Figma across all platforms.
Component is available in code for web and mobile web.
Component is not currently available in code for iOS.
Component is not currently available in code for Android.
If additional functionality is needed in the menu, such as subtext, headers or custom styling, use Dropdown.
If users need the ability to choose an option by entering text to filter a long list of options, use ComboBox.
If users need the ability to choose between fewer than 4 options, use RadioButton.
If users need the ability to choose between a yes/no option, use Checkbox.