Table of Contents

Multiselect

Multiselect lets users select multiple items from a list. Options are dynamically filtered as a user types in the input field and their selections appear as tags in the input field.

Table of Contents

How to use it
Configuration
API

Deprecated

Multiselect does not meet Web Content Accessibility Guidelines (WCAG) requirements. Use Combobox instead.

Used for this

To choose multiple items from a list of options
To filter through a set of data by typing

How to use it

Default

The typical usage of a Multiselect component.

Hidden label

Multiselect labels can be hidden.

Overflow

A Button indicating the number of “overflowing” Tags lets users see any Tags that don’t fit.

Size

Multiselect comes in two sizes: default or compact.

Configuration

Name8.76.4•View source•View on npm
Installnpm install @zendeskgarden/react-dropdowns
Depsnpm install react react-dom styled-components @zendeskgarden/react-theming
Importimport { Dropdown, Field, Hint, Label, Multiselect, Item } from '@zendeskgarden/react-dropdowns'

API

The Multiselect component follows this structure:

<Dropdown>  <Field>    <Label />    <Hint />    <Multiselect />  </Field>  <Menu>    <Item />    <Item />    {/* etc. */}  </Menu></Dropdown>

Implementation notes

The dropdowns package does not have filtering logic. The simplest way to include filtering is to control the inputValue and onInputValueChange props, and conditionally render Item components as necessary.
Use the onInputValueChange prop instead of or in combination with onStateChange for more accurate IME (Input Method Editor) support
There is a known issue with Google Translate. As a workaround, wrap any conditionally rendered text node with a span element.

The Dropdown component provides state and accessibility to its consumers while enabling customization. It uses PopperJS for positioning.

Dropdown State: The Downshift library handles keyboard and accessibility logic. Provide other customizations directly to Downshift via downshiftProps. See the stateReducer pattern for a common customization strategy example.

Server Side Rendering: Server side rendering might require specific Downshift settings. The dropdowns package re-exports Downshift’s resetIdCounter utility, resetting the internal counter which is used to generate unique IDs for Downshift.

Prop name	Type	Default	Description
downshiftProps	Record<string, any>	–	Passes customization props to the Downshift component
highlightedIndex	number	–	Highlights an element at a selected index
inputValue	string	–	Sets the value of the input element
isOpen	boolean	–	Opens the dropdown
onInputValueChange		–	Handles input value change Parameters `inputValue` Value of the input element `stateAndHelpers` Downshift state and helpers
onSelect		–	Handles item selection Parameters `selectedItem` The selected item `stateAndHelpers` Downshift state and helpers
onStateChange		–	Handles state change Parameters `options` Downshift internal state changes `stateAndHelpers` Downshift state and helpers
selectedItem	any	–	Identifies the currently selected item
selectedItems	any[]	–	Identifies the currently selected items

Field

Extends HTMLAttributes<HTMLDivElement>

A Field provides accessibility attributes to the child Multiselect field by associating it with the corresponding Label and Hint.

Hint

Extends HTMLAttributes<HTMLDivElement>

Nest a Hint within a Field component.

Item

Extends LiHTMLAttributes<HTMLLIElement>

Nest an Item within a Menu component. It requires a value prop, which is provided to the onSelect callback.

Prop name	Type	Default	Description
disabled	boolean	–	Indicates that the element is not interactive
isDanger	boolean	–	Applies danger styling
value	any	–	Sets the value that is returned upon selection

Label

Extends LabelHTMLAttributes<HTMLLabelElement>

Nest a Label within a Field component.

Prop name	Type	Default	Description
hidden	boolean	–	Hides the label visually without hiding it from screen readers
isRegular	boolean	–	Applies regular (non-bold) font weight

Multiselect

Extends HTMLAttributes<HTMLDivElement>

The Multiselect component applies state and accessibility attributes to its children. Nest it within a Field component. It renders a customizable tag for each selected item. This tag can be any element, but the surrounding field is designed to work with the Tag component.

Prop name	Type	Default	Description
disabled	boolean	–	Indicates that the element is not interactive
focusInset	boolean	–	Applies inset `box-shadow` styling on focus
inputRef	Ref<HTMLInputElement>	–	Provides ref access to the underlying input element
isBare	boolean	–	Removes borders and padding
isCompact	boolean	–	Applies compact styling
maxItems	number	4	Determines the maximum number of items displayed while collapsed
placeholder	string	–	Defines text that appears in the element when no items are selected
renderItem		Required	Renders each item element. Designed to be used with Tag. Parameters `options` Rendered item options `options.value` The item value `options.removeValue` Remove item callback Returns item element
renderShowMore		–	Overrides the "+ N more" text displayed when the total number of items exceeds `maxItems` Parameters `value` The number of hidden items Returns replacement for the "+ N more" text
start	any	–	Defines the icon rendered before the element's content
validation	'success' \| 'warning' \| 'error'	–	Applies validation state styling