Skip to content
Change the site theme


Peer review pending

A Combobox is a styled dropdown form element that allows users to either type a value or select a value from a list.


Guidelines page anchor

About Combobox

About Combobox page anchor

The Combobox is an opinionated implementation and wrapper around the very excellent Downshift componentlink takes you to an external page.

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.

When the user is focused on a Combobox, the following keyboard interactions apply:

  • Up and down arrows move the user between the options
  • Enter selects the currently active option

Basic Combobox

Basic Combobox page anchor

Combobox using Option Template

Combobox using Option Template page anchor

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)

Combobox with add-ons (prefix/suffix text or icons) page anchor
  • 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).
Get more info

Combobox with option groups

Combobox with option groups page anchor

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.

This is the help text

Combobox with custom group label

Combobox with custom group label page anchor

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.

This is the help text

The Combobox can be used as a controlled componentlink takes you to an external page 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.

Input value state: ""
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"}]
Warning icon
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 Downshiftlink takes you to an external page.

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.

This is the help text
Input value state: ""
Selected item state: {}

Combobox with inline error

Combobox with inline error page anchor
This is the error message
PropertyDefault tokenModifiable?
Label text
  • $font-size-30
  • Default: $color-text, $font-weight-semibold
  • Disabled: $color-text-weaker, $font-weight-semibold
Required field indicator
  • 4px size (0.25rem)
  • Background: $color-background-required
Box Shadow
  • Default: $shadow-border
  • Hover: $shadow-border-primary-strong
  • Disabled: $shadow-border-weak
  • Error: $shadow-border-error
  • Error hover: $shadow-border-error-strong
  • Default: $color-background-body
  • Disabled: $color-background
  • Background: $color-background
  • Border: $color-border-weaker
Prefix/suffix text
  • Default: $color-text
  • Disabled: $color-text-weak
Help text$color-text-weak, $font-size-30No
Inline error
  • Text: $color-text-error, $font-size-30
  • Icon: IconError, $color-text-error, $icon-size-20
  • Label:
    • Bottom: $space-10
    • Between label and required indicator: $space-20
  • Input:
    • Left padding: $space-40
    • Top, right, bottom padding: $space-30
  • Prefix/suffix padding: $space-30
  • Help text:
    • Top: $space-20
  • Inline error:
    • Spacing between icon and text: $space-20
    • Top: $space-20
  • Icon: IconChevronDown, $space-20 from left

yarn add @twilio-paste/combobox - or - yarn add @twilio-paste/core
import {Combobox} from '@twilio-paste/core/combobox';
const Component = () => <Combobox autocomplete items={foo} labelText="Foo" helpText="Bar" />;

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.

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.

See the Combobox Primitive.