Skip to contentSkip to navigationSkip to topbar
Paste
Paste assistant Assistant
FigmaStar

Multiselect Combobox

Version 16.3.1GithubStorybook

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

Installation

Installation page anchor
yarn add @twilio-paste/combobox - or - yarn add @twilio-paste/core

Usage

Usage page anchor
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

Props page anchor

ComboboxListbox

ComboboxListbox page anchor

hidden RequiredRequired

Type
boolean

element

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

Type
string
Default
COMBOBOX_LISTBOX

ComboboxListboxOption

ComboboxListboxOption page anchor

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
string
Default
COMBOBOX

highlighted

Type
boolean

selected

Type
boolean

startHeight

Type
number

ComboboxListboxGroup

ComboboxListboxGroup page anchor

element

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

Type
string
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

MultiselectCombobox

MultiselectCombobox page anchor

items RequiredRequired

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

Type
any[]

labelText RequiredRequired

The contents of the label text

Type
NonNullable<ReactNode>

selectedItemsLabelText RequiredRequired

Hidden helper text for screen readers

Type
string

cursor

Type
| Cursor | (Cursor | null | undefined)[] | { [x: string]: Cursor | undefined; [x: number]: Cursor | undefined }

disabled

Disables the input.

Type
boolean

disabledItems

Type
any[]

element

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

Type
string
Default
MULTISELECT_COMBOBOX

emptyState

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

Type
FC<{}>

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

hasError

Sets the input to an error state.

Type
boolean

height

Type
never

helpText

The contents of the help and error text

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

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.

i18nStepDownLabel

Provides an accessible label for the decrement button on inputs of type "number" when using non-English languages.

Type
string

i18nStepUpLabel

Provides an accessible label for the increment button on inputs of type "number" when using non-English languages.

Type
string

initialIsOpen

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

Type
boolean

initialSelectedItems

Sets the initial items selected when initialized

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
string

insertAfter

Used to add a suffix to an input. Often used with text or an icon.

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

insertBefore

Used to add a prefix to an input. Often used with text or an icon.

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

itemToString

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

Type
(item: any) => string

maxHeight

The maximum height of the Combobox listbox

Type
| string | number | (string & {}) | (MaxHeightOptions | null)[] | { [x: string]: MaxHeightOptions; [x: number]: MaxHeightOptions }
Default
100%

name

Sets the name of the input.

Type
string

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
(changes: UseComboboxStateChange<any>) => void

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
(changes: UseComboboxStateChange<any>) => void

onIsOpenChange

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

Type
(changes: UseComboboxStateChange<any>) => void

onSelectedItemsChange

Callback function for after an item is selected or deselected

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

optionTemplate

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

Type
OptionTemplateFn<any>

padding

Type
"space0"

paddingRight

Type
"space0" | "space10" | "space20" | "space30" | "space40" | "space50" | "space60" | "space70" | "space80" | "space90" | "space100" | "space110" | "space120" | "space130" | "space140" | ... 38 more ... | { ...; }

placeholder

Sets the placeholder of the input.

Type
string

readOnly

Sets the input to readonly.

Type
boolean

required

Sets the input as required.

Type
boolean

size

Type
never

state

Type
UseMultipleSelectionReturnValue<Item>

style

Type
never

usePortal

Determines whether the Combobox Listbox (options list) is rendered inside a Portal. Defaults to true. Use false if you are using Combobox inside a Paste Popover to prevent interaction bugs.

Type
boolean
Default

variant

Type
InputVariants
Default
default

width

Type
never

Combobox

Combobox page anchor

items RequiredRequired

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

Type
any[]

labelText RequiredRequired

The contents of the label text

Type
NonNullable<ReactNode>

autocomplete

Activates the autocomplete/typeahead feature

Type
boolean

cursor

Type
| Cursor | (Cursor | null | undefined)[] | { [x: string]: Cursor | undefined; [x: number]: Cursor | undefined }

disabled

Disables the input.

Type
boolean

disabledItems

Type
any[]

element

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

Type
string
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
(options: A11yStatusMessageOptions<any>) => string

getA11yStatusMessage

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

Type
(options: A11yStatusMessageOptions<any>) => string

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

hasError

Sets the input to an error state.

Type
boolean

height

Type
never

helpText

The contents of the help and error text

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

hideVisibleLabel

Type
boolean

i18nStepDownLabel

Provides an accessible label for the decrement button on inputs of type "number" when using non-English languages.

Type
string

i18nStepUpLabel

Provides an accessible label for the increment button on inputs of type "number" when using non-English languages.

Type
string

initialIsOpen

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

Type
boolean

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
string

insertAfter

Used to add a suffix to an input. Often used with text or an icon.

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

insertBefore

Used to add a prefix to an input. Often used with text or an icon.

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

itemToString

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

Type
(item: any) => string

name

Sets the name of the input.

Type
string

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
(changes: UseComboboxStateChange<any>) => void

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
(changes: UseComboboxStateChange<any>) => void

onIsOpenChange

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

Type
(changes: UseComboboxStateChange<any>) => void

onSelectedItemChange

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

Type
(changes: UseComboboxStateChange<any>) => void

optionTemplate

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

Type
OptionTemplateFn<any>

padding

Type
"space0"

paddingRight

Type
"space0" | "space10" | "space20" | "space30" | "space40" | "space50" | "space60" | "space70" | "space80" | "space90" | "space100" | "space110" | "space120" | "space130" | "space140" | ... 38 more ... | { ...; }

placeholder

Sets the placeholder of the input.

Type
string

readOnly

Sets the input to readonly.

Type
boolean

required

Sets the input as required.

Type
boolean

selectedItem

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

Type
any

size

Type
never

state

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

Type
Partial<UseComboboxReturnValue<any>>

style

Type
never

usePortal

Determines whether the Combobox Listbox (options list) is rendered inside a Portal. Defaults to true. Use false if you are using Combobox inside a Paste Popover to prevent interaction bugs.

Type
boolean
Default

variant

Type
InputVariants
Default
default

width

Type
never