Usage

MultiSelector picks several values from a fixed list. Without a search field, the trigger is a combobox. The menu is a listbox with aria-multiselectable. Choosing an option leaves the menu open.

An option can be a string, an object with a description, a divider, or a labeled section. selectAll adds a row that toggles every enabled option and skips disabled ones. searchable filters that same list. It does not call a remote source.

triggerDisplay controls the closed trigger. count shows how many are selected, labels joins the text, and badges uses tokens. maxBadges limits how many are visible, and the rest collapse to +N. A narrower trigger collapses further.

Read-only keeps the selection, stays focusable, and still submits. It does not open, and it has no clear button or chevron. It does not dim. While loading, the trigger shows a spinner, the create row stays hidden, and the menu does not claim the list is empty. disabledMessage explains a disabled field: a tooltip follows hover and keyboard focus, the trigger stays focusable through aria-disabled, and the menu still does not open.

A function can replace the closed text for the count and labels displays. Badges ignore it. An empty selection does not call it and keeps the placeholder.

Create works together with search. When the typed text matches no option label, ignoring case, the first row offers to create it. Choosing that row adds a description to the change event: the kind is create, and the text is the query. Add that option to the list in the same update. Without search, the create row never appears.

To open the menu from outside, pass the handle object itself from script. A template unwraps a ref, so pass a function that receives the handle. Open does nothing while the field is read-only or disabled.

Arrow keys move the highlight. Enter and Space toggle the highlighted option. Space inside the search field still types. Enter creates the current text when nothing is highlighted. Escape closes the menu. When the menu is closed and the user is not searching, Backspace clears the selection.

Best Practices

Guideline	Practice
Do	Use Multi Selector when the list is short and people need to compare the choices.
Do	Use badges and +N when the closed trigger should still name the selection.
Don't	Search a remote source with Multi Selector. Use Tokenizer for that.

Anatomy

Element	Description
Field	Standalone Field shell that provides the label and optional supporting content; omitted inside InputGroup.
Trigger	Painted control that displays the current selection or placeholder and opens the selection surface when editable.
Icon-rendered start icon	Optional leading semantic icon or icon component rendered through Icon.
Caller-rendered start content	Optional arbitrary slot content rendered directly at the start of the trigger.
Trigger clear button	Shared clear action that removes every selected value when clearable is set.
Status icon	Status glyph shown in place of the disclosure indicator for attached or tooltip status.
Indicator icon	Trailing chevron shown when status presentation does not replace it; reflects collapsed or expanded state.
Search row	Panel header with a borderless search input and optional clear action.
Search icon	Leading magnifier rendered through Icon inside the search row.
Search clear button	Shared clear action shown in the search row while a query is present.
Option row	Selectable row for an option or the optional select-all choice.
Option checkbox indicator	CheckboxInput indicator that presents each row’s selected, unselected, or indeterminate state.
Option divider	Divider supplied in the public options data to separate adjacent option groups.
Section heading	Visible heading for a labeled group of option rows.
Empty state	Message shown when the shared panel content has no options or no search matches.
Pointer popup	Anchored painted surface that hosts the shared panel content for popover presentation.
Touch sheet heading	Heading above the shared panel content in bottom-sheet presentation.
Touch sheet	BottomSheet surface that hosts the same panel content for bottom-sheet presentation.

Examples

Bottom Sheet

Teams

Teams

Keeps a multi-selection list open in a bottom sheet while choices are toggled.

Column Visibility

Columns

Column visibility toggle with hidden label, search, select-all, and selection count.

Form Composition

Visible columns ∙ Required

Choose which columns to display in the table

Status filter ∙ Optional

Filter by status

+1

Locked columns

Ask an administrator to change the saved view

Two multi-selectors in a form with required and optional states, plus a disabled one that explains itself on hover or keyboard focus.

Ghost Toolbar

Columns

Status

Some filters hide archived rows

Borderless variant composed with ghost buttons in a toolbar.

Searchable

Countries

Multi-select with search filtering and select-all.

Sectioned Permissions

Permissions

Multi-select with options grouped into labeled sections.

Create and read-only

Permissions

Summary

Locked

Read only

Typing a name that is not in the list offers to create it. The closed text can be a custom sentence. Read-only keeps the selection.