Skip to content
Change the site theme
Figma
(information)

Multiselect Combobox

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


Guidelines

Guidelines page anchor

About Multiselect Combobox

About Multiselect Combobox page anchor

A Multiselect Combobox allows a user to either type or select multiple values from a styled listbox of options. Each option can consist of more than just text, e.g. text paired with an icon.

What’s the difference between Select and Comboboxes?

What’s the difference between Select and Comboboxes? page anchor

At its most basic, a Select has an options list that’s styled according to the browser default. A Combobox has a Twilio-styled options list and can allow for additional functionality like autocomplete and multiselect.

Use a Select when:

  • You need a native picker experience, especially on mobile devices.
  • Users will be selecting from a list of 4-10 options, or a sorted list of highly familiar options (e.g., alphabetical list of states or countries).
  • You need the component to work out-of-the-box across all operating systems and browsers.

Use a Multiselect Combobox when:

  • You need a Twilio-styled options list.
  • You need to show more than text in an option (e.g., text paired with an icon).
  • You need to group options under labels.
  • You need to disable options in the list.
  • Users would benefit from autocomplete functionality (e.g., autocomplete, search). For example, autocomplete may be useful when users need to select from a list of more than 10 options.
  • You need to lazy load a much longer list of options to improve page load performance.

Multiselect Combobox is built with consideration for the ARIA combobox pattern(link takes you to an external page).

When a user is focused on a Combobox, the listbox opens. When a user makes a selection, the listbox closes so the selected option can be registered to screen readers.

Keyboard interaction

Keyboard interaction page anchor

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

When the user is focused within the Form Pill Group, they can use these keyboard interactions:

  • Left and right arrow keys move focus within the group.
  • If a pill is selectable, spacebar and enter will toggle pill selection.
  • If a pill is dismissible, the pill can be removed by pressing the delete or backspace key.

Basic Multiselect Combobox

Basic Multiselect Combobox page anchor

Use a basic Multiselect Combobox to allow users to select multiple values from a list of predefined options.

The height of the Combobox field will increase to fit the selection of Form Pills. Optionally, you may set a max height using the maxHeight prop and if there are more pills than viewable at max height, users can vertically scroll to view all the selected options.

Multiselect Combobox with add-ons (prefix/suffix text or icons)

Multiselect Combobox with add-ons (prefix/suffix text or icons) page anchor

Use add-ons to provide users with guidance on formatting their input and to offer more context about the value a user is entering.

  • Prefix/suffix text — Text that can be used as a prefix and/or suffix to the value that is entered. Use prefix/suffix to help users format text.
  • Prefix/suffix icon — Icons can be placed in the same area as the prefix and suffix text. Icons should trigger an action (e.g., clearing a field) or in rare cases, provide further context to what value should be entered to make a field's purpose more immediately visible (e.g., a search icon).

Multiselect Combobox with option groups

Multiselect Combobox with option groups page anchor

Use option groups to create labeled sections of options.

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.

Multiselect Combobox with a custom group label

Multiselect Combobox with a custom group label page anchor

Expanding on the previous example, it's also possible to customize the group label.

The groupLabelTemplate prop accepts a method with a groupName argument. This method should return valid JSX, which it will render in place of a group label string.

In the example below, we are checking the groupName and rendering an icon next to it based on the name.

Multiselect Combobox with option template

Multiselect Combobox with option template page anchor

Use the option template to display more complex options in a listbox.

The optionTemplate prop allows you to pass jsx to customize the options. Note that we use native HTML input elements to build Combobox and these HTML elements don't allow for images, icons, or svgs to be added even with the option template.

Multiselect Combobox with max height

Multiselect Combobox with max height page anchor

By default the Multiselect Combobox will grow to fit the content inside it. If you want to limit how much it resizes vertically, you can provide a maxHeight prop.

Disabled Multiselect Combobox

Disabled Multiselect Combobox page anchor

Multiselect Combobox with disabled options

Multiselect Combobox with disabled options page anchor

Multiselect Combobox with error

Multiselect Combobox with error page anchor

Multiselect Combobox with an empty state

Multiselect Combobox with an empty state page anchor

Use an empty state to indicate to a user that their input does not match any value in the list of options.

A Multiselect Combobox is comprised of a label, an input and a listbox.

Stack form fields vertically with $space-80 spacing between each field. Avoid placing multiple form fields on the same horizontal row to help make it easier to scan a page vertically.

Keep option text concise and simple. Option text will truncate when it’s longer than the width of the container. Use a safe and reversible option as the default selected value.

Use at least 7 options in a Combobox. If there are less than 7 options or if choosing options requires more explanation, consider using a Checkbox instead and add Help Text for each option, or give more explanation through help text. Sort options logically (e.g., alphabetically, by value) or in an order that’s intuitive to your user.

When to use Multiselect Combobox

When to use Multiselect Combobox page anchor
Do

Use a Multiselect Combobox when there are multiple options for a user to type or select.

Don't

Don’t use a Multiselect Combobox when a user should only select a single option. Use a Singleselect Combobox instead.

Do

Use a Multiselect Combobox when there are at least 7 options for a user to type or select from.

Don't

Don’t use a Multiselect Combobox if there are less than 7 options in a list for users to select multiple values from. Use a Checkbox Group instead.


yarn add @twilio-paste/combobox - or - yarn add @twilio-paste/core
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);
}}
/>
);
);
PropTypeDescriptionDefault
labelTextstring \| NonNullable<React.ReactNode>The contents of the label text.
selectedItemsLabelTextstringHidden helper text for screen readers''
groupItemsBy?stringThe name of the key in your item objects that you would like Combobox to group the items by.
groupLabelTemplate?(groupName: string) => React.ReactNodeThis function allows you to use your own jsx template for the group label in the drop-down list.
helpText?string \| React.ReactNodeThe contents of the help and error text.
optionTemplate?(item: string \| {}) => React.ReactNodeThis function allows you to use your own jsx template for the items in the drop-down list.
element?stringOverrides the default element name to apply unique styles with the Customization Provider'MULTISELECT_COMBOBOX'
variant?'default' \| 'inverse'The variant of the Combobox. Available variants are default or inverse.'default'
disabled?booleanSame as the HTML attribute
hasError?booleanWhether or not the Combobox has an error.false
required?booleanSame as the HTML attributefalse
i18nKeyboardControls?stringVisually hidden string that has instructions for how to remove and select pills with a keyboard."Press Delete or Backspace to remove. Press Enter to toggle selection."
maxHeightstringThe maximum height of the Combobox listbox.
PropTypeDescriptionDefault
itemsany[]The items to be displayed in the Combobox listbox.[]
itemToString?(item: any) => stringA function that returns a string value that uniquely identifies each item in the items array.item => item
inputValue?stringSets the value of the input inside the Combobox.''
initialIsOpen?booleanWhether the Combobox is open on initial render.false
initialSelectedItems?any[]Sets the initial items selected when initialized.[]
disabledItems?any[]An array of items that should be disabled.[]
emptyState?React.FCA custom empty state component to render when there are no items in the list.null
onSelectedItemsChange?(newSelectedItems: any[]) => voidCallback function for after an item is selected or deselected.
onHighlightedIndexChange?(newHighlightedIndex: number) => voidCallback function for after an item is highlighted. Items are highlighted if they are hovered over or with keyboard actions.
onInputValueChange?(newInputValue: string) => voidCallback function for after the input value is changed.
onIsOpenChange?(newIsOpen: boolean) => voidCallback function for after the Combobox is opened or closed.