Multiselect Combobox

A Multiselect Combobox is a styled dropdown form element that allows users to select multiple values from a list.

Installation

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

Usage

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

const items = [
  'Alert',
  'Anchor',
  'Button',
  'Card',
  'Heading',
  'List',
  'Modal',
  'Paragraph',
  'Popover',
  'Tooltip',
];

function getFilteredItems(inputValue) {
  const lowerCasedInputValue = inputValue.toLowerCase();

  return items.filter(function filterItems(item) {
    return item.toLowerCase().includes(lowerCasedInputValue);
  });
}

const MyComponent = () => (
  const [inputValue, setInputValue] = React.useState('');
  const filteredItems = React.useMemo(() => getFilteredItems(inputValue), [inputValue]);

  return (
    <MultiselectCombobox
      labelText="Choose a Paste Component"
      selectedItemsLabelText="Selected Paste components"
      items={filteredItems}
      onInputValueChange={({inputValue: newInputValue = ''}) => {
        setInputValue(newInputValue);
      }}
    />
  );
);

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