Combobox
A Combobox combines a text input with an icon-only chevron button. When activated, a dropdown menu of selectable options displays.
Guidelines
Using comboboxes
Through comboboxes, users can input text, numbers, symbols or mixed-format strings (unless specifically restricted) while being offered autocomplete options in a dropdown menu.
Use the Combobox component when it's difficult to predict the user's response to a prompt. It provides predefined input values as options, for example common responses, to ease filling out the input with relevant values.
Specifications
- Icon (optional)
Icons may be added to simplify the identification of specific combobox inputs. - Placeholder text (optional)
The placeholder text provides an example of what type of information is being requested in the input. The placeholder text should further illustrate and support the combobox input label. However, it should never be the only input description. - Chevron button
An icon-only chevron button opens the menu. - Menu
When the combobox is active, a menu with options is displayed.
Refer to the Combobox component in Codex Figma.
Interaction states
Comboboxes have the following visually separate states:
- Default
- Hover on input
- Hover on button
- Disabled
- Active with menu displayed
- Active and hover on one of the menu items
- Typing in the input and having a menu item selected based on the matching text
- Combobox filled with one selected menu option
Demos
Basic Usage
The Combobox component combines a menu of selectable items with a text box that can accept arbitrary input from the user. The component should receive a v-model:selected
binding from its parent as well as an array of menu items (which can be empty).
Selected value:
Name | Value |
---|---|
View | |
Reading direction |
Clearable, with start icon
Valid TextInput props like startIcon
, endIcon
, and clearable
will be passed on to the embedded TextInput
.
Selected value:
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 Combobox to bold the label text and hide the text overflow of the descriptions.
With custom menu item display
Like other menu-style components (Select
, Lookup
, etc.), a custom template can be provided via the #menu-item
slot. In this example, only the menu item's icon is displayed in the menu.
With "no results" content
A non-interactive "no results" message can be displayed via the no-results
slot. If populated, this slot will automatically display when there are zero menu items.
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.
Disabled
Form field
A Combobox 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
TextInput props apply
This component contains a TextInput component. You can bind TextInput props to this component and they will be passed to the TextInput within.
Attributes passed to input
This component will pass any HTML attributes applied to it, except for CSS class, to the <input>
element within the component.
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 . | string|number | - | |
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; } |
status | status property of the TextInput component | ValidationStatusType | 'default' , 'error' | 'default' |
Events
Event name | Properties | Description |
---|---|---|
input | event InputEvent | When the input value changes via direct use of the input |
change | event Event | When an input value change is committed by the user (e.g. on blur) |
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 | selected string|number - The new selected value | When the selected value changes. |
focus | event FocusEvent | When the input comes into focus |
blur | event FocusEvent | When the input loses focus |
Slots
Name | Description | Bindings |
---|---|---|
menu-item | Display of an individual item in the menu | menu-item MenuItemData - The current menu item |
no-results | Message to show if there are no menu items to display. |