Skip to content

Multi Select

⋯

Multi Select implements the approved Figma anatomy as a separate Base UI Combobox primitive. It combines a count-based trigger, search input, multiple-selection list, option metadata, empty results, and Reset and Select all actions.

Import MultiSelect from @nesra/ui/multi-select or @nesra/ui. Each item requires a unique string value and searchable label.

import { MultiSelect } from "@nesra/ui/multi-select";
export function TeamChoice() {
return (
<MultiSelect
label="Teams"
name="teams"
items={[
{ value: "engineering", label: "Engineering" },
{ value: "design", label: "Design" },
]}
/>
);
}
MultiSelect
├── Field label
├── count trigger
└── searchable popup
├── search input
├── option list or empty state
└── Reset / Select all actions

Pass MultiSelect.Option children when an option needs custom markup. Every custom option value must also appear in items, because items owns search labels, selected-value resolution, and bulk selection.

summary is application-owned trigger content. The component does not infer business totals from option metadata.

The page owns value and updates it through onValueChange.

Selected: engineering

sm, md, and lg render 36px, 40px, and 44px triggers. The disabled state prevents opening or selection.

error replaces the description and gives the trigger the destructive border and ring. The trigger keeps a 1px border when focused or open. Colors follow the field state colors in Light and Dark.

MultiSelect.Option forwards Base UI item behavior and adds the optional trailing count badge.

When name is set, each selected string is submitted under that name. required asks the browser to reject an empty selection.

Opening the trigger moves focus to the search input. Typing filters against item labels. Arrow keys move through enabled options, Enter toggles the highlighted option, and Escape closes the popup and returns focus to the trigger. Selecting an option keeps the popup open and preserves the current query. emptyTitle and emptyDescription replace the default empty-search copy.

Reset clears the selection. Select all selects every enabled item in items, including items hidden by the current query. Set showActions={false} when those bulk actions do not fit the product rule.

Base UI supplies combobox, dialog, listbox, and option semantics; multiple-selection state; keyboard navigation; disabled-item skipping; Escape dismissal; and focus return. label names both the trigger and popup search input. Supply aria-label when no visible label is rendered. Each option exposes its selected state semantically; the selected check icon is decorative.

Applications own item loading, labels, translated copy, count meaning, selection limits, validation timing, and any relationship between selected options and summary. The component does not fetch data or validate business rules.

Prop Type Default Effect
items readonly MultiSelectItem[] required Supplies searchable options, labels, metadata, and disabled state.
children MultiSelect.Option[] generated options Replaces generated option markup while retaining items as data.
value readonly string[] — Controls selected values.
defaultValue readonly string[] [] Initializes uncontrolled selection.
onValueChange (value, details?) => void — Reports option changes and bulk actions. Details are absent for bulk actions.
label, aria-label ReactNode, string — Names the trigger and search input. Use one of them.
description, error ReactNode, FieldError — Renders help text or a replacing validation message.
placeholder ReactNode Select options Renders while no values are selected.
size "sm" | "md" | "lg" "sm" Sets the trigger height to 36px, 40px, or 44px.
summary ReactNode | (items) => ReactNode — Adds application-owned text after the selected count.
renderValue (items) => ReactNode — Replaces the default n selected trigger content.
searchPlaceholder string Search Sets the search hint.
popupLabel string Options Names the popup dialog.
emptyTitle, emptyDescription ReactNode generic empty copy Sets the empty-search message.
showActions boolean true Shows Reset and Select all.
resetLabel, selectAllLabel ReactNode Reset, Select all Sets bulk-action copy.
name, form, required Base UI form props — Controls native form ownership, submission, and required validation.
disabled, readOnly boolean false Prevents interaction or selection edits.
open, defaultOpen, onOpenChange Base UI open-state props — Controls popup state.
side, align, sideOffset Base UI Positioner props bottom, start, 4 Positions the popup. Offset is in pixels.
className string — Styles the Field container.
triggerClassName, contentClassName, listClassName Base UI class values — Styles the trigger, popup, and list.
container portal container document.body Selects the portal host.

MultiSelectItem accepts required value and label strings plus optional supportingText, count, and disabled. Values must be unique, and controlled values must match an item so the trigger can resolve their labels.

value is required and must match an item. count renders the trailing badge. The part forwards Base UI Item props, including disabled, className, event handlers, and a div ref.

See Colors, Typography, Layout, and Shape and elevation for the semantic tokens used by the trigger and popup.