MultiSelect
Choose multiple collection items in a searchable tag field.
Anatomy#
MultiSelect renders its portaled popup internally; the popup names are style slots, not attached parts. Replace tags with tagRender.
Usage#
Use MultiSelect for several collection items shown as tags, or for creatable free-form tags. Each
value resolves through a collection item. Use Select for one non-editable
choice, Combobox for editable single selection, or
BaseSelect to compose the listbox yourself. Unlike Select and Combobox,
items takes item objects only, with no string shorthand.
Values and tag lifecycle#
value is the array of selected item values, in selection order. An empty array means no
selection, and an empty string can be an item value. Pair value with onValueChange for controlled
selection, or use defaultValue for an initial uncontrolled selection. onValueChange receives the
full new array and clears the search text afterward. Without searchable, printable keys trigger
collection typeahead. Set searchable to let users type in the field to filter options.
clearable shows a clear button while there are selected values or search text. It does not always
empty a MultiSelect: selected values whose items are disabled stay selected because the user cannot
remove them, and values that match no item are dropped. Every other selection is cleared, the search
text is emptied, and onClear runs after onValueChange. Select and Combobox clear to an empty
value instead.
Search and item creation#
searchable and createItem decide whether the field is editable. Filtering follows editability, so
the four combinations behave as follows:
searchable |
createItem |
Field | Filters options | Creates items | openOnControlClick default |
|---|---|---|---|---|---|
| unset | unset | Trigger button, no text input | No | No | true |
true |
unset | Editable input | Yes | No | false |
| unset | set | Editable input | Yes | Yes | false |
true |
set | Editable input | Yes | Yes | false |
searchable alone filters the collection as the user types. createItem makes the input editable and
enables creation. It also filters the list, so searchable adds nothing once createItem is set.
filterMethod and autocomplete have no effect on a non-editable control.
openOnControlClick defaults to the opposite of editability. A non-editable control opens its popup
on click. An editable control focuses its input on click and opens from typing, the chevron button,
or ArrowDown. Set openOnControlClick explicitly to change either default.
Item creation and delimiters#
createItem receives the trimmed query text when the user commits text that matches no existing item
by label or value, and returns the TItem to select. The item is added to the top of the option list
until a native form reset. Nothing is created when the value is already selected or maxValues is
reached. Commit text with Enter, a token separator, or paste; all go through the same creation path.
tokenSeparators defaults to [','].
Keyboard interaction#
| Key | Behavior |
|---|---|
| Backspace | With an empty input, remove the last removable tag |
| ArrowLeft | At the start of the input, focus the last tag’s remove button |
| ArrowLeft / Right | On a remove button, focus the neighboring removable tag, or return to the input |
| Backspace / Delete | On a remove button, remove that tag and focus a neighbor |
| ArrowDown / ArrowUp | Open the popup and move the highlight through enabled options |
| Enter | Commit the highlighted option, or create an item from the input text |
| Escape | Close the popup; the search text resets once it closes |
| Tab | Close the popup and move focus on |
Virtualization#
Pass a virtualizer from createListVirtualizer when rendering the full collection makes opening
or scrolling slow. Type it over MultiSelectT.Row. Read the Virtualization guide
for setup, row measurement, stable keys, and keyboard navigation.
Examples#
Color issue labels#
Use tagRender to style tags from item data such as a color class. Selected values still come
from the collection.
Assign project members#
Search teammates and keep each selection as a tag. Put the email or role in description.
Cap selection and visible tags#
maxValues blocks additional selections by disabling unselected options. maxVisible is visual:
surplus selections stay committed and collapse into a +N summary. Use tagOverflowRender to
render the hidden tags yourself, for example in a tooltip.
Create a missing topic#
Pass createItem and an emptyRender action so unmatched text can become a collection item.
The create function in the emptyRender state runs createItem for the current search text.
Enter free-form tags#
With no predefined items, combine createItem and tokenSeparators for a tag input. Comma, space,
and paste all create tokens.
Grant grouped permissions#
Organize a large permission set with type: 'group'. Group labels are not selectable.
Lock required modules#
Disable an option to keep it in the list without allowing toggle. disabled and readOnly on the
root freeze the whole control.
Search a large collection#
Pass a createListVirtualizer instance as virtualizer when opening or scrolling the full list is
slow.
Require a minimum number of tags#
Validate the selected array with createForm. Use a minLength schema rule to fail short
selections; required only checks that something is selected. A selection made only of disabled
items passes constraint validation but submits no value to the native form, as a native
<select multiple> does.
API Reference#
Attributes#
data-closeddata-disableddata-editabledata-expandeddata-invaliddata-readonlydata-requireddata-tagsdata-sidedata-highlighteddata-selecteddata-duplicatedata-loadingProps#
Renders a <div> element by default.