Components
MultiSelect
A multi-value combobox with removable tags, search, selection limits, and custom value rendering.
MultiSelect extends the Select interaction model to multiple values using Base UI's Combobox
primitives with chip rendering. Selected options render as removable chips, and the listbox exposes
aria-multiselectable.
Import it from @orkest/ui/client.
Live preview#
import { useState } from 'react';
import { MultiSelect } from '@orkest/ui/client';
const skills = [
{ value: 'react', label: 'React' },
{ value: 'typescript', label: 'TypeScript' },
{ value: 'node', label: 'Node.js' },
{ value: 'css', label: 'CSS' },
{ value: 'testing', label: 'Testing' },
{ value: 'accessibility', label: 'Accessibility' },
];
export function Example() {
const [selected, setSelected] = useState(['react', 'typescript']);
return (
<MultiSelect
aria-label="Skills"
options={skills}
value={selected}
onChange={(nextValues) => setSelected(nextValues)}
searchable
hideSelected
clearable
maxSelected={3}
placeholder="Select skills"
/>
);
}Selection, search, and tags#
Each selected value renders as a removable tag. Removing a tag updates the value array immediately.
clearable adds a clear action that removes every selection. With searchable, typing filters the
menu; hideSelected removes already selected options from the menu so only remaining choices are
shown.
<MultiSelect
aria-label="Skills"
options={skills}
defaultValue={['react']}
searchable
hideSelected
clearable
/>Selection limits#
maxSelected disables unselected options once the limit is reached. Selected options stay
interactive so the user can replace a choice. The field shows the current count as selected/max
at the right edge.
<MultiSelect aria-label="Skills" options={skills} maxSelected={3} />Custom value content#
Override the default tags with renderValue. The callback receives selected options and a remove
function:
<MultiSelect
aria-label="Skills"
options={skills}
defaultValue={['react', 'typescript']}
renderValue={(selected, remove) => (
<span>
{selected.length} selected
<button type="button" onClick={() => remove('react')}>
Remove React
</button>
</span>
)}
/>Props#
| Prop | Type | Default |
|---|---|---|
options | Array<SelectOption | SelectOptionGroup> | — |
| Options and option groups rendered in the listbox. | ||
value | string[] | — |
| Controlled selected values. | ||
defaultValue | string[] | [] |
| Initial values for uncontrolled usage. | ||
onChange | (value: string[], options: SelectOption[]) => void | — |
| Called with the next values and their options. | ||
maxSelected | number | — |
| Limits how many options can be selected and shows the current count as selected/max. | ||
hideSelected | boolean | false |
| Removes selected options from the menu. | ||
renderValue | (selected: SelectOption[], remove: (value: string) => void) => ReactNode | — |
| Replaces the default tag display. | ||
removeLabel | string | 'Remove' |
| Accessible label prefix for tag remove actions. | ||
placeholder | string | 'Select options' |
| Text shown when nothing is selected. | ||
searchable | boolean | false |
| Enables the search input and local filtering. | ||
searchPlaceholder | string | 'Search…' |
| Placeholder for the search input while the menu is open. | ||
onSearchChange | (query: string) => void | — |
| Called when the query changes, including reset on close. | ||
filterOption | (option: SelectOption, query: string) => boolean | — |
| Replaces the default case-insensitive label filter. | ||
emptyMessage | ReactNode | 'No options' |
| Content shown when no options match. | ||
loading | boolean | false |
| Shows a loading row and sets aria-busy on the listbox. | ||
clearable | boolean | false |
| Shows a clear action while values are selected. | ||
clearLabel | string | 'Clear selection' |
| Accessible name for the clear action. | ||
disabled | boolean | false |
| Disables the entire control and its remove actions. | ||
required | boolean | false |
| Marks the field required and forwards it to Base UI hidden form inputs. | ||
invalid | boolean | false |
| Applies the danger border and aria-invalid. | ||
size | 'sm' | 'md' | 'lg' | 'md' |
| Control and tag size using the shared control tokens. | ||
name | string | — |
| Form field name applied to one hidden input per value. | ||
id | string | — |
| Id applied to the combobox input. | ||
className | string | — |
| Class name applied to the root element. | ||
leftIcon | LucideIcon | — |
| Decorative icon rendered before the selected values. | ||
aria-label / aria-labelledby | string | — |
| Accessible name for the combobox and listbox. | ||
aria-describedby / aria-errormessage | string | — |
| Connects help text and validation messages. | ||
Accessibility#
- Base UI renders the combobox input and the popup uses
role="listbox"witharia-multiselectable="true". Selected options exposearia-selected="true". ArrowDown/ArrowUpbrowse options,Entertoggles the highlighted option, andEscapecloses the popup and restores focus.Tableaves the field.- When
searchableis true, typing filters options andSpaceinserts a space. Without search, the input is read-only and the chevron trigger opens the popup. - Default chips include a labelled remove action, and Base UI handles Backspace/Delete removal while
a chip is focused.
renderValuereplaces the chip content; its wrapper stops click propagation so custom controls do not toggle the popup. requiredandnameare forwarded to the hidden form inputs managed by Base UI.- The input exposes the selected count through
aria-description.