Combobox

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

Installation

yarn add @twilio-paste/combobox - or - yarn add @twilio-paste/core

Usage

import {Combobox} from '@twilio-paste/core/combobox';

const authors = [
  'James Baldwin',
  'Adrienne Maree Brown',
  'Octavia Butler',
  'Ta-Nehisi Coates',
  'Audre Lorde',
  'Nnedi Okorafor',
];

const Component = () => <Combobox autocomplete items={authors} labelText="Select an author" required />;

Props

ComboboxListbox

hidden RequiredRequired

Type: boolean

element

Overrides the default element name to apply unique styles with the Customization Provider

Type: any
Default: COMBOBOX_LISTBOX

Inherited props

ComboboxListboxOption

variant RequiredRequired

Type: "default" | "groupOption"
Default: default

disabled

Type: boolean

element

Overrides the default element name to apply unique styles with the Customization Provider

Type: any
Default: COMBOBOX

highlighted

Type: boolean

selected

Type: boolean

startHeight

Type: number

Inherited props

ComboboxListboxGroup

element

Overrides the default element name to apply unique styles with the Customization Provider

Type: any
Default: COMBOBOX

groupLabelTemplate

This function allows you to use your own jsx template for the group label in the drop-down list

Type: (groupName: string) => ReactNode

groupName

Overrides the default element name to apply unique styles with the Customization Provider

Type: string

Inherited props

MultiselectCombobox

selectedItemsLabelText RequiredRequired

Hidden helper text for screen readers

Type: string

element

Overrides the default element name to apply unique styles with the Customization Provider

Type: any
Default: MULTISELECT_COMBOBOX

i18nKeyboardControls

Visually hidden string that has instructions for how to remove and select pills with a keyboard

Type: string
Default: Press Delete or Backspace to remove. Press Enter to toggle selection.

initialSelectedItems

Sets the initial items selected when initialized

Type: any[]

maxHeight

The maximum height of the Combobox listbox

Type: any
Default: 100%

onSelectedItemsChange

Callback function for after an item is selected or deselected

Type: ( newSelectedItems: UseMultiSelectPrimitiveStateChange<Item> ) => void

state

Type: any

Inherited props

Combobox

labelText RequiredRequired

The contents of the label text

Type: NonNullable<ReactNode>

autocomplete

Activates the autocomplete/typeahead feature

Type: boolean

disabledItems

Type: any[]

element

Overrides the default element name to apply unique styles with the Customization Provider

Type: any
Default: COMBOBOX

emptyState

A custom empty state component to render when there are no items in the list

Type: FC<{}>

getA11ySelectionMessage

Downshift useCombobox Hook Prop (see https://github.com/downshift-js/downshift/blob/master/src/hooks/useCombobox/README.md#advanced-props docs)

Type: any

getA11yStatusMessage

Downshift useCombobox Hook Prop (see https://github.com/downshift-js/downshift/blob/master/src/hooks/useCombobox/README.md#advanced-props docs)

Type: any

groupItemsBy

The name of the key in your item objects that you would like Combobox to group the items by

Type: string

groupLabelTemplate

This function allows you to use your own jsx template for the group label in the drop-down list

Type: (groupName: string) => ReactNode

helpText

The contents of the help and error text

Type: | string | number | boolean | ReactElement<any, string | JSXElementConstructor<any>> | ReactFragment | ReactPortal

hideVisibleLabel

Type: boolean

initialIsOpen

Downshift useCombobox Hook Prop (see https://github.com/downshift-js/downshift/blob/master/src/hooks/useCombobox/README.md#advanced-props docs)

Type: any

initialSelectedItem

Downshift useCombobox Hook Prop (see https://github.com/downshift-js/downshift/blob/master/src/hooks/useCombobox/README.md#advanced-props docs)

Type: any

inputValue

Downshift useCombobox Hook Prop (see https://github.com/downshift-js/downshift/blob/master/src/hooks/useCombobox/README.md#advanced-props docs)

Type: any

items

Downshift useCombobox Hook Prop (see https://github.com/downshift-js/downshift/blob/master/src/hooks/useCombobox/README.md#advanced-props docs)

Type: any

itemToString

Downshift useCombobox Hook Prop (see https://github.com/downshift-js/downshift/blob/master/src/hooks/useCombobox/README.md#advanced-props docs)

Type: any

onChange

Use onInputValueChange instead.

Type: never

onHighlightedIndexChange

Downshift useCombobox Hook Prop (see https://github.com/downshift-js/downshift/blob/master/src/hooks/useCombobox/README.md#advanced-props docs)

Type: any

onInput

Use onInputValueChange instead.

Type: never

onInputValueChange

Downshift useCombobox Hook Prop (see https://github.com/downshift-js/downshift/blob/master/src/hooks/useCombobox/README.md#advanced-props docs)

Type: any

onIsOpenChange

Downshift useCombobox Hook Prop (see https://github.com/downshift-js/downshift/blob/master/src/hooks/useCombobox/README.md#advanced-props docs)

Type: any

onSelectedItemChange

Downshift useCombobox Hook Prop (see https://github.com/downshift-js/downshift/blob/master/src/hooks/useCombobox/README.md#advanced-props docs)

Type: any

optionTemplate

This function allows you to use your own jsx template for the items in the drop-down list

Type: OptionTemplateFn<any>

selectedItem

Downshift useCombobox Hook Prop (see https://github.com/downshift-js/downshift/blob/master/src/hooks/useCombobox/README.md#advanced-props docs)

Type: any

state

Downshift useCombobox Hook return props for when you are using the hook outside of the component

Type: any

variant

Type: any
Default: default