Select
A Select is an input with a dropdown menu of predefined, selectable items.
Guidelines
Using selects
Selects must feature a label stating the current selection and a menu of at least two, but preferably three or more, options.
Use the Select component when users need to choose an option from a predefined list. For example, to select a country or category. If the list of options is too long, consider using Combobox instead. If users need a multi-selection, use a Checkbox group instead.
Specifications
- Icon (optional)
An icon can simplify the identification of the available options in selects. - Label
Dropdown labels communicate what selections the component conveys. Labels are required for selects. - Arrow indicator
Selects have a button-like appearance, and include a mandatory arrow indicator to communicate that they can be expanded. - Menu
When the select is open, a menu with options is displayed.
Refer to the Select component in Codex Figma.
Interaction states
Selects have the following visually separate states:
- Default
- Hover
- Focus
- Error
- Disabled
- Active select with menu displayed
- Active select and hover on one of the menu options
- Active select and one of the menu options being pressed
- Active select with one of the menu options selected
- Filled (with one option from the menu selected)
Accessibility note
The disabled state does not meet our minimum color contrast rules. WCAG 2.1 states that “…part[s] of an inactive user interface component […] have no contrast requirement”. [1]
Provide sufficient information in a disabled element's context, so the user can understand what is disabled and how to enable it (if applicable).
References
Demos
Configurable
Name | Value |
---|---|
Props | |
disabled | |
defaultLabel | |
defaultIcon | |
status | |
View | |
Reading direction | |
Note: For icon properties, the relevant icon also needs to be imported from the @wikimedia/codex-icons package. See the usage documentation for more information. |
Basic Usage
Menu items must have a value, and can have a label to display in the UI. If no label is provided (like the third menu item in this example), the value will be displayed.
With menu item icons and descriptions
Items are displayed via the MenuItem component—see the MenuItem docs for more options. In this example, a menuConfig
object is passed to the Select to bold the label text and hide the text overflow of the descriptions.
With custom menu item display
The menu-item
scoped slot enables you to customize the display of each menu item, with a binding for the menuItem
. In this example, only the menu item's icon is displayed in the menu.
With custom label display
The label
scoped slot enables you to customize the display of the label, with bindings for the selectedMenuItem
and the defaultLabel
.
With configurable scroll
By default, all menu items are displayed when the menu is expanded. To limit the height of the menu and enable scrolling, use the visibleItemLimit
property of the menuConfig
prop.
Form field
A Select can be wrapped in the Field component to add features like a semantic label, description and help text, validation messages, and more. See the Field page for more information.
Vue usage
Menu items are provided as an array of MenuItemData types, and v-model
is used to bind the current selection's value.
Props
Prop name | Description | Type | Values | Default |
---|---|---|---|---|
menuItems (required) | Menu items. See the MenuItemData type. | MenuItemData[] | - | |
selected (required) | Value of the current selection. Must be bound with v-model:selected .The property should be initialized to null rather than using a falsy value. | string|number|null | - | |
defaultLabel | Label to display when no selection has been made. | string | - | '' |
disabled | Whether the dropdown is disabled. | boolean | - | false |
menuConfig | Configuration for various menu features. All properties default to false. See the MenuConfig type. | MenuConfig | - | () => { return {} as MenuConfig; } |
defaultIcon | An icon at the start of the select element displayed when no selection has been made. | Icon|undefined | - | undefined |
status | status attribute of the input. | ValidationStatusType | 'default' , 'error' | 'default' |
Events
Event name | Properties | Description |
---|---|---|
load-more | When the user scrolls towards the bottom of the menu. If it is possible to add or load more menu items, then now would be a good moment so that the user can experience infinite scrolling. | |
update:selected | modelValue string|number|null - The new model value | When the selection value changes. |
Slots
Name | Description | Bindings |
---|---|---|
label | Display of the current selection or default label | selected-menu-item MenuItemData, undefined - The currently selected menuitem default-label string - The default label, provided via a prop |
menu-item | Display of an individual item in the menu | menu-item MenuItemData - The current menu item |
CSS-only version
Markup structure
The CSS-only version of this component uses the native <select>
element. This element will be styled to match the Vue version, but the menu will use native browser styles.
Disabled
Add the disabled
attribute to the <select>
element to get a disabled element with appropriate styles.