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" }, ]} /> );}Composition
Section titled “Composition”MultiSelect├── Field label├── count trigger└── searchable popup ├── search input ├── option list or empty state └── Reset / Select all actionsPass 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.
Examples
Section titled “Examples”Selected count and option counts
Section titled “Selected count and option counts”summary is application-owned trigger content. The component does not infer business totals from
option metadata.
import { MultiSelect, type MultiSelectItem } from "@nesra/ui/multi-select";
const teams: MultiSelectItem[] = [ { value: "engineering", label: "Engineering", supportingText: "12 users", count: 3 }, { value: "design", label: "Design", supportingText: "10 users", count: 3 }, { value: "product", label: "Product", supportingText: "6 users", count: 3 }, { value: "marketing", label: "Marketing", supportingText: "8 users", count: 3 }, { value: "sales", label: "Sales", supportingText: "12 users", count: 3 }, { value: "customer-success", label: "Customer Success", supportingText: "4 users", count: 3, }, { value: "operations", label: "Operations", supportingText: "2 users", count: 3 }, { value: "finance", label: "Finance", supportingText: "5 users", count: 3 },];
export function BasicMultiSelectExample() { return ( <MultiSelect aria-label="Teams" className="w-[284px] max-w-full" items={teams} defaultValue={["engineering", "design"]} placeholder="Select teams" summary="16 users" /> );}Controlled selection
Section titled “Controlled selection”The page owns value and updates it through onValueChange.
import { MultiSelect, type MultiSelectItem } from "@nesra/ui/multi-select";import { useState } from "react";
const teams: MultiSelectItem[] = [ { value: "engineering", label: "Engineering", supportingText: "12 users" }, { value: "design", label: "Design", supportingText: "10 users" }, { value: "product", label: "Product", supportingText: "6 users" },];
export function ControlledMultiSelectExample() { const [value, setValue] = useState<string[]>(["engineering"]);
return ( <div className="w-full max-w-80"> <MultiSelect label="Teams" items={teams} value={value} onValueChange={setValue} /> <p className="mt-2 type-nesra-body-small-regular"> Selected: {value.length > 0 ? value.join(", ") : "none"} </p> </div> );}Sizes and disabled
Section titled “Sizes and disabled”sm, md, and lg render 36px, 40px, and 44px triggers. The disabled state prevents opening or
selection.
import { MultiSelect, type MultiSelectItem } from "@nesra/ui/multi-select";
const teams: MultiSelectItem[] = [ { value: "engineering", label: "Engineering" }, { value: "design", label: "Design" },];
export function MultiSelectSizesExample() { return ( <div className="grid w-full max-w-80 gap-6"> <MultiSelect aria-label="Small team selector" items={teams} size="sm" /> <MultiSelect aria-label="Medium team selector" items={teams} size="md" /> <MultiSelect aria-label="Large team selector" items={teams} size="lg" /> <MultiSelect aria-label="Disabled team selector" items={teams} disabled /> </div> );}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.
import { MultiSelect, type MultiSelectItem } from "@nesra/ui/multi-select";
const teams: MultiSelectItem[] = [ { value: "engineering", label: "Engineering", supportingText: "12 users" }, { value: "design", label: "Design", supportingText: "10 users" }, { value: "product", label: "Product", supportingText: "6 users" },];
export function ErrorMultiSelectExample() { return ( <MultiSelect className="w-[284px] max-w-full" label="Teams" items={teams} placeholder="Select teams" error="Choose at least one team." required /> );}Custom options
Section titled “Custom options”MultiSelect.Option forwards Base UI item behavior and adds the optional trailing count badge.
import { MultiSelect, type MultiSelectItem } from "@nesra/ui/multi-select";
const teams: MultiSelectItem[] = [ { value: "engineering", label: "Engineering", count: 3 }, { value: "design", label: "Design", count: 2 }, { value: "operations", label: "Operations", disabled: true },];
export function MultiSelectCustomOptionsExample() { return ( <MultiSelect className="w-full max-w-80" label="Teams" items={teams}> {teams.map((team) => ( <MultiSelect.Option key={team.value} value={team.value} count={team.count} disabled={team.disabled} > <span className="font-medium">{team.label}</span> {team.disabled && <span className="ml-1 text-nesra-text-support">Unavailable</span>} </MultiSelect.Option> ))} </MultiSelect> );}Native form submission
Section titled “Native form submission”When name is set, each selected string is submitted under that name. required asks the browser
to reject an empty selection.
import { Button } from "@nesra/ui/button";import { MultiSelect, type MultiSelectItem } from "@nesra/ui/multi-select";import { useState, type SubmitEvent } from "react";
const teams: MultiSelectItem[] = [ { value: "engineering", label: "Engineering" }, { value: "design", label: "Design" }, { value: "product", label: "Product" },];
export function MultiSelectFormExample() { const [submitted, setSubmitted] = useState<string[]>([]);
function handleSubmit(event: SubmitEvent<HTMLFormElement>) { event.preventDefault(); setSubmitted(new FormData(event.currentTarget).getAll("teams").map(String)); }
return ( <form className="grid w-full max-w-80 gap-4" onSubmit={handleSubmit}> <MultiSelect label="Teams" items={teams} name="teams" required /> <Button type="submit">Submit</Button> {submitted.length > 0 && ( <p className="type-nesra-body-small-regular">Submitted: {submitted.join(", ")}</p> )} </form> );}Search and empty results
Section titled “Search and empty results”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.
Accessibility
Section titled “Accessibility”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.
API reference
Section titled “API reference”MultiSelect
Section titled “MultiSelect”| 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.
MultiSelect.Option
Section titled “MultiSelect.Option”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.