Combobox
Comboboxes are a type of select field that allow users to choose from a list of options.
- Make sure combobox fields look interactive
- The combobox field's state (blank, with input, error, etc) should be visible at a glance
- Keep labels and error messages brief and easy to act on
- Combobox fields commonly appear to assist in list selection
Example
Live Playground
Resources
| Name | Resource | Status |
|---|---|---|
| Figma | Design Kit (Figma) | Private |
On this page
Usage
Standard Combobox
Responsive Layout
As layouts adapt to larger screens and different window sizes, apply flexible container dimensions to select fields. Set minimum and maximum values for margins, padding, and container dimensions as layouts scale so that typography adjusts for better reading experiences.
Select fields can span the full width of the display on compact window sizes, but should be bounded by flexible margins or other containers on medium and expanded window sizes.
On this page
import { Combobox, ComboItemGroup, ComboItemWithIndicator, ComboItemText} from '@cerberus/react'Usage
The Combobox component is an abstraction component that provides a fully functional combobox. It is built on top of the Select component and allows additional functionality such as filtering.
With Start Icon
To add an icon to the start position of the input, use the startIcon prop to pass in your ReactNode.
Grouped Items
To group items, use the ComboItemGroup component (not ComboboxItemGroup).
With Field
Wrap the Combobox component with the Field component to add additional functionality such as error and helper text when using it in a form.
Primitives
You can utilize the primitive components to customize the select.
| Component | Description |
|---|---|
| ComboboxRoot | The context provider for the combobox family |
| ComboboxLabel | The label that appears above the combobox input |
| ComboboxControl | The wrapper to the combobox trigger that opens the dropdown |
| ComboboxInput | The input field of the combobox |
| ComboboxTrigger | he trigger that opens the dropdown |
| ComboboxClearTrigger | The trigger that clears the selected value |
| ComboboxPositioner | The wrapper that positions the dropdown |
| ComboboxContent | The content of the dropdown (i.e. the container itself) |
| ComboboxItemGroup | The group of options in the dropdown |
| ComboboxItemGroupLabel | The label for the group of options |
| ComboboxItem | The option in the dropdown |
| ComboboxItemText | The text label of the option |
| ComboboxItemIndicator | The indicator shown when the option is selected |
API
Combobox
The Combobox component is an abstraction of our primitives and accepts the following props:
| Name | Default | Description |
|---|---|---|
| size | 'md' | The size of the combobox. |
| startIcon | The icon to display at the start of the input. |
The Combobox component also accepts all the props of the ComboboxRoot primitive props
ItemWithIndicator
The ItemWithIndicator component is an abstraction of our primitives and accepts all the props of the ComboboxItem primitive props
ComboItemGroup
The ComboItemGroup component is an abstraction of our primitives and accepts the following props:
| Name | Default | Description |
|---|---|---|
| label | The label of the group. |
The ComboItemGroup component is an abstraction of our primitives and accepts all the props of the ComboboxItemGroup primitive props
useStatefulCollection
The useStatefulCollection function is a utility hook that creates a collection of options and filters the list based on the user input.
function useStatefulCollection( initialItems: SelectCollectionItem[] = [],): StatefulCollectionReturnReturns
| Name | Description |
|---|---|
| collection | The collection of options. |
| filterChars | The filter value split into an Array of chars. |
| handleInputChange | The function to pass to onInputValueChange. |
Parts
The ComboboxParts API is an Object containing the full family of components.
| Name | Description |
|---|---|
| Root | The ComboboxRoot component which is the Provider for the family. |
| Label | The ComboboxLabel component which displays the label. |
| Control | The ComboboxControl component which is the container for the visual field. |
| Input | The ComboboxInput component which is the visual field. |
| Trigger | The ComboboxTrigger component which is the trigger for the dropdown. |
| ClearTrigger | The ComboboxClearTrigger component which is the trigger to clear the value. |
| Positioner | The ComboboxPositioner component which is controls the positioning for the dropdown. |
| Content | The ComboboxContent component which is the dropdown itself. |
| ItemGroup | The ComboboxItemGroup component which is the group of options in the dropdown. |
| ItemGroupLabel | The ComboboxItemGroupLabel component which is the label for the group of options. |
| Item | The ComboboxItem component which is the option in the dropdown. |
| ItemText | The ComboboxItemText component which is the text label of the option. |
| ItemIndicator | The ComboboxItemIndicator component which displays based on the checked state. |
On this page
Use Cases
- Users should be able to:
- Navigate to and activate a select field with assistive technology
- Choose an item from the list of options
- Receive and understand supporting select and error messages
Keyboard Navigation
| Keys | Actions |
|---|---|
| Tab | Focus lands on (non-disabled) input |
| Enter | Opens the dropdown menu and selects the focused option |
| Esc | Closes the dropdown menu |
Labeling Elements
If the UI text is correctly linked, assistive tech (such as a screenreader) will read the UI text followed by the component's role.
The accessibility label for a select field is typically the same as the label for the text field.
On this page