Combobox
An accessible styled drop-down list box.
- Status
- alpha
- Version
- 7.0.0
- Import from
@twilio-paste/core/combobox— or —@twilio-paste/combobox
Using alpha components in your product
Alpha components are ready for you to use in production. Components such as Combobox are likely to not see any API changes. This is only an alpha due to the lack of documentation and minimal design. Feel free to share your experience using this component at #help-design-system or start a discussion on GitHub.
Guidelines#
About Combobox#
The Combobox is an opinionated implementation and wrapper around the very excellent Downshift component.
Combobox allows a user to make a selection from a styled list box of options. Each option can consist of more than just text, e.g. text paired with an icon. It can also be set up with autocomplete/typeahead functionality so users can easily find a specific option.
Examples#
Basic Combobox#
Autocomplete Combobox#
Combobox using Option Template#
The optionTemplate prop allows you to pass jsx in order to display more complex items in the list box.
Combobox with add-ons (prefix/suffix text or icons)#
- Prefix/suffix text - Text that can be used as a prefix or suffix to the value that is entered. Use prefix/suffix to help users format text.
- Icon - Icons that can be placed in the same area as the prefix and suffix text. Icons should trigger an action (e.g., opening a popover).
Combobox with option groups#
The list of options shown to the user, known as the Listbox, can be grouped to create labelled sections. Structure your data into an array of objects and use a key on each object as the grouping identifier. Then tell the Combobox what you would like to group the items by, by setting groupItemsBy to match the intended group identifier.
In the example below we have a list of components and we are grouping them based on their type.
Combobox with custom group label#
You can control the contents of the group label is a similar way to options, by providing a custom template. The groupLabelTemplate prop takes a method with groupName argument, that you can use to return valid JSX from. It will render the contents of that JSX as a child of the group label.
In the example below we are checking the groupName and rendering an icon next to it based on the name.
Controlled Combobox#
The Combobox can be used as a controlled component when you would like full control over your state. Use the properties selectedItem, inputValue, onInputValueChange and onSelectedItemChange to control the value of the Combobox via your own application state.
In the example below the value of the Combobox is stored in a piece of our application state. We update that value based on user input into the Combobox, resetting the value of the Combobox. Upon the user selecting a defined option, we hook into onSelectedItemChange to set our selectedItem state value based on user selection.
Selected item state:
Items state: [{"label":"November","year":"2020","abbr":"Nov"},{"label":"December","year":"2020","abbr":"Dec"},{"label":"January","year":"2021","abbr":"Jan"},{"label":"February","year":"2021","abbr":"Feb"}]
useCombobox state hook#
🚨Power user move!🚨
Only use this property if you are a power user. It's very easy to break your implementation and unfortunately the Paste team will not be able to debug this for you. Proceed with extreme caution.
In addition to being a controlled component, the Combobox comes with the option of "hooking" into the internal state by using the state hook originally provided by Downshift.
Rather than the state be internal to the component, you can use the useCombobox hook and pass the returned state to Combobox as the state prop.
This allows you to destructure certain returned props from the state hook, including action methods like reset.
An example usecase of this might be programmatically providing the user a way to clear or reset the Combobox of it's previous selections. In the example below we are providing a clear button as an input suffix. When pressed, it uses the reset action method from the hook to clear the input and select item values.
It should be noted that when doing so, the state prop takes precident over the other properties that affect the state or initial state of the Combobox. They will be ignored in favour of them being provided as arguments to the useCombobox hook.
For full details on how to use the state hook, and what props to provide it, follow the Combobox Primitive documentation. It's the same hook, just renamed.
Selected item state: {}
States#
Disabled Combobox#
Combobox with inline error#
Anatomy#
| Property | Default token | Modifiable? |
|---|---|---|
| Label text |
| No |
| Required field indicator |
| No |
| Box Shadow |
| No |
| Background |
| No |
| Prefix/suffix |
| No |
| Prefix/suffix text |
| No |
| Help text | $color-text-weak, $font-size-30 | No |
| Inline error |
| No |
| Spacing |
| No |
| Chevron |
| No |
Usage Guide#
API#
Installation#
yarn add @twilio-paste/combobox - or - yarn add @twilio-paste/coreUsage#
import {Combobox} from '@twilio-paste/combobox';const Component = () => <Combobox autocomplete items={foo} labelText="Foo" helpText="Bar" />;Component Props#
All the valid HTML attributes for input are supported including the following props:
autocomplete?: boolean
Allows autocomplete/typehead feature.
groupItemsBy?: string
The name of the key in your item objects that you would like Combobox to group the items by.
groupLabelTemplate?: (groupName: string) => React.ReactNode
This function allows you to use your own jsx template for the group label in the drop-down list.
helpText?: string | React.ReactNode
The contents of the help and error text.
labelText: string | NonNullable<React.ReactNode>
The contents of the label text.
optionTemplate?: (item: string | {}) => React.ReactNode
This function allows you to use your own jsx template for the items in the drop-down list.
variant?: string
The variant of the Combobox. Available variants are default or inverse.
State Props#
These props are used when want to create a Controlled Combobox. They control the state of the Combobox.
initialIsOpen?: boolean
Sets whether the Combobox is open on initial render.
initialSelectedItem?: Item
Sets the initial item selected when a Combobox is initialized.
inputValue?: string
Sets the value of the input inside the Combobox.
items: Item[]
Array of items to be displayed in the option list.
itemToString?: (item: Item) => string
If items are stored as an object, used to convert item to a string.
onHighlightedIndexChange?: (changes: Partial<UseComboboxState<Item>>) => void
This function is called each time the highlighted item was changed. Items are highlighted if they are hovered over or with keyboard actions.
onInputValueChange?: (changes: Partial<UseComboboxState<Item>>) => void
This function is each time the value of the input changes.
onIsOpenChange?: (changes: Partial<UseSelectState<Item>>) => void
This function is each time the value of the input changes.
onSelectedItemChange?: (changes: Partial<UseSelectState<Item>>) => void
This function is called each time the selected item changes. Items are selected by click or the enter key while highlighted.
selectedItem?: any
Used to set the Selected Item of the Combobox.
state?: Partial<UseComboboxPrimitiveReturnValue<Item>>
Used as a replacement the state props when coupled with using the useCombobox hook. When using this prop, all other state props are ignored. They must be passed to useCombobox as arguments instead.
useCombobox Arguments#
Please see the Combobox Primitive.