Multiselect
<Multiselect>
is a type of multiple selection interface that displays options in a list format with the ability to select multiple items.
It allows users to choose multiple options by clicking on the items in the list and provides a comprehensive view of available options and the selected items.
The previous multiselect recipe pattern has been replaced by this official MultiSelect component. Existing implementations using the recipe pattern should migrate to this component for better accessibility and keyboard navigation.
Anatomy
The <MultiSelect>
component combines a text input with a ListBox, enabling users to select multiple options that are displayed as removable tags within the input field.

Label: Descriptive text guiding the user on what information is required in the input field.
Input field: A text box where users can enter or edit data.
Dropdown arrow: An icon indicating that more options are available; clicking it reveals a list of selectable items.
Overlay: Hold a list of all possible options which can be selected.
Tag: Hold selected item.
Appearance
The appearance of a component can be customized using the variant
and size
props. These props adjust the visual style and dimensions of the component, available values are based on the active theme.
Property | Type | Description |
---|---|---|
variant | - | The available variants of this component. |
size | - | The available sizes of this component. |
Usage
The Multiselect component exhibits notable accessibility challenges with keyboard navigation. When interacting with disabled options, the focus indicator becomes obscured, preventing the expected behavior of skipping disabled items. This lack of clear visual feedback during navigation can temporarily confuse users. Note: This accessibility limitation stems from the react-select library's implementation
The <MultiSelect>
component works best when users need to select multiple items from a large list of options (10+) and see their choices displayed as compact tags directly in the input. It’s helpful when you want to combine filtering (typing to narrow options) with visible selection feedback, saving space compared to checkboxes while allowing users to dynamically add or remove tags during the selection process.
Avoid using MultiSelect when users need to pick a single option, the list is small, space isn’t an issue or search isn't necessary.
Controlled
The onSelectionChange
and onChange
props can be used to control the Multiselect
.
Current Input:
Selected Priorities:
Props
aria-errormessage?
string;
aria-invalid?
boolean | "false" | "true" | "grammar" | "spelling";
aria-label?
string;
aria-labelledby?
string;
aria-live?
"off" | "assertive" | "polite";
ariaLiveMessages?
AriaLiveMessages<unknown, boolean, GroupBase<unknown>>;
autoFocus?
boolean;
defaultSelectedItems?
unknown;
defaultValue?
string;
description?
ReactNode;
disabled?
boolean;
"false"
error?
boolean;
"false"
errorMessage?
string | ((validation: ValidationResult) => string);
isOptionDisabled?
(option: unknown, selectValue: Options<unknown>) => boolean;
items?
OptionsOrGroups<unknown, GroupBase<unknown>>;
label?
ReactNode;
noOptionsMessage?
(obj: { inputValue: string }) => ReactNode;
onBlur?
FocusEventHandler<HTMLInputElement>;
onChange?
(newValue: string, actionMeta: InputActionMeta) => void;
onFocus?
FocusEventHandler<HTMLInputElement>;
onSelectionChange?
(newValue: unknown, actionMeta: ActionMeta<unknown>) => void;
placeholder?
string;
readOnly?
boolean;
"false"
required?
boolean;
"false"
selectedItems?
unknown;
width?
WidthProp;
Alternative components
Choosing the right alternative to <Multiselect>
is important for providing an optimal user experience, especially when different types of selections are required. Depending on the nature of the choices and the desired interaction, the following components can serve as an alternative to Multiselect:
- SelectList: When you need more than just a text label to represent options, a
<SelectList>
can be used instead. - TagGroup: When you want to visually highlight selected options as individual tags or want a horizontal list of options, use the
<Tag>
component. - Checkbox: When your list items may contain interactive elements such as buttons, checkboxes, menus .