Select

selection sets behavior, indicator sets the single-select mark.

selection="single" (the default) keeps value a single value and closes on pick. indicator then picks the row mark: "none" (default; a tint-only highlight), "check" (a trailing checkmark on the chosen row that keeps the tint, the canonical Select look), or "radio" (a leading radio on every row).

selection="multiple" makes value an array, puts a checkbox on every row, keeps the menu open as you toggle, and summarises the selection in the field: All when every option is on, the single label for one, else “N selected” (pass verbose to spell the picks out — 3 selected: A, B, C; or take over the text entirely with renderSummary; an empty selection shows the placeholder). A Select all top row shows by default; it toggles everything, and its box goes mixed when only some are on. Pass selectAll={false} to drop it.

In a multi-select, Alt+Click a row to clear every other selection and select that row. On macOS, use Option instead of Alt. After hovering for 700ms, the standard tooltip describes this shortcut beside the row. Moving to another row restarts the delay. Set SelectOption.tooltip to replace it, or to '' to hide it. The shortcut is available only when selectAll is enabled, so selectAll={false} removes it.

Each checkable row is the control itself (role="menuitemcheckbox" / menuitemradio, aria-checked); the checkbox / radio / check is a passive indicator the row drives.

Use tone with toneScope="selected" to tone only selected rows: the whole row takes the tone, including label, icon, indicator, and tint. Pass a named tone or any CSS color (a custom color keeps its hue, with lightness pinned to the brand text). It reads strongest with indicator none / check, which show the row tint; radio / checkbox have no row tint, so it tones the label and indicator only.

Add filter for a search field at the top of the menu that narrows the options as you type. true uses the built-in matcher: a case-insensitive substring of the option’s value, label, or hint. It’s whitespace-flexible (a typed space matches any run of whitespace) and bolds the matched substring in the results. Pass a function (option, query) => boolean for custom matching (no highlight).

With filter, the trigger opens a dialog containing the search field and an options menu. This keeps the textbox outside the menu in the accessibility tree. Opening the dialog focuses the search field. ↑ and ↓ move through matching options while focus stays in that field. Enter selects the active option, and Esc closes the dialog. The search field stays visible while the results scroll. A “No matches” row appears when nothing matches, and the query resets when the dialog closes. In multiple mode, selectAll affects only the visible matches.

The value is the option’s value — value="stream" in single mode, an array like value={['stream', 'container']} in multiple. It’s the option’s identity: what value / defaultValue name and what onValueChange reports, so keep each option’s value unique across the whole tree. Selection is value-keyed and global across groups / submenus, so a value repeated in two sections is one logical pick (both rows toggle together; the trigger resolves to the last). Dev builds console.warn on a duplicate.

Values aren’t limited to strings. Select infers its value type from options: pass options={[{ value: 365 }, { value: 90 }]} and value, onValueChange’s value, and attrs.value are all number (the same for boolean). Values compare with ===, so 365 and "365" stay distinct and no string conversion is needed. The exported OptionValue type is string | number | boolean; for anything richer (a date, an object), give value a stable primitive key (a date’s ISO string, a record’s id) and read the full value back off attrs.option.

// Use the ID as the value and attach the full record to the option.
<Select
  options={runs.map((r) => ({ value: r.id, label: r.name, run: r }))}
  onValueChange={(id, attrs) => { if (!('all' in attrs)) openRun(attrs.option.run) }}
/>

// Use an ISO string as the value, then convert it back to a Date in the callback.
<Select
  options={days.map((d) => ({ value: d.toISOString(), label: fmt(d) }))}
  onValueChange={(iso) => setDay(new Date(iso))}
/>

For an uncontrolled Select, omit value and pass defaultValue. For a controlled Select, pass value and update it in onValueChange. The field then shows the value supplied by the application.

onValueChange(value, attrs) is the single selection callback. The new value comes first (a single value, or an array in multiple mode), with a snapshot second: { value, option } for the changed row, plus selected in multiple mode (or { all: true } for the Select-all row). There’s no onStateChange: Select has no discrete element state to veto (Checkbox and RadioGroup do), so it follows Input’s model of one value callback, and a controlled consumer rejects a pick by not updating value. See the event-model note on Input for the rationale.

The trigger is an Anta Button styled as a field. size (small · medium · large) sets the height and type scale. status paints a validation tone on the border, hint, and chevron, and prefixes a glyph (info / success / warning / critical); statusIcon overrides that glyph (any shape, or false to drop it), as on Input. The message rides in hint.

status is a validation state over the same palette as tone: it also carries the glyph and, for critical, validity. See the Input status note. The field also takes label, placeholder, round, and disabled, and fills its container; set a width via style / className (both forwarded to the field).

renderOption(option, state) replaces the built-in label, hint, and icon layout for a row. Select still renders the row container, click behavior, ARIA attributes, and selection indicator. Set each option’s label for the closed field text.

Attach your own fields to each option (SelectOption carries an index signature) and read them back off option; those extra fields are typed unknown, so cast once at the top. state gives you value / selected / disabled for the row. Give your root flex: 1; min-width: 0 so it fills the row (an inner margin-inline-start: auto right-aligns a trailing element, like the status Tag here).

filter still matches the option’s value, label, and hint. Select does not highlight matches in custom content because it cannot identify text within the returned node. indicator and selection still provide the selection mark. Use renderIndicator to replace that mark too; see Custom indicators.

A menu grows to fit its widest row. The trigger width sets the floor; the viewport sets the ceiling. Built-in labels stay bounded (they wrap), but custom renderOption content does whatever your CSS says, so wide content stretches the whole menu. Open both dropdowns: same rows, yet the first grows past its 220px field while the second (capped) stays put and ellipsizes.

Enforce the limit on the menu: cap it with ::part(menu) { max-width }. Only then does ellipsis-ready content truncate, so give the row a shrinkable box (min-width: 0) and single-line ellipsis (overflow: hidden; text-overflow: ellipsis; white-space: nowrap). Nest a Tooltip truncatedOnly in that element to reveal the full text on hover, only when it’s clipped. min-width: 0 alone won’t bound it: a shrink-to-fit popover grows to its content’s max-content width, so the cap is what does the work.

renderSummary(selected) builds the multi-select field text in place of the built-in “All / one label / N selected”. It runs while something is selected — an empty selection still shows the placeholder — and takes the resolved selected options (selected.length is the count). Return undefined for any case you’d rather leave to the default, as above for the single-label case.

Return a string: it flows into the same Button label the default uses, so a long summary ellipsizes at the field’s width the way a long value does (Engineering, Design, … ). For rich content — chips, several nodes — reach for renderTrigger below, which replaces the whole field.

For the common case of just listing the picks, skip renderSummary and pass verbose: the count summary becomes 3 selected: A, B, C (labels comma-joined), ellipsizing at the field width like any long value. renderSummary overrides it.

renderTrigger(state) replaces the default field. Return exactly one focusable element, such as the Anta Button in this example. Select positions the menu relative to that element and opens it when it is clicked. A fragment, multiple sibling elements, or a non-focusable wrapper prevents Select from finding the trigger. It logs a console warning when that happens. Add aria-haspopup={filter ? 'dialog' : 'menu'} and aria-expanded={state.open} to the element.

state includes open, value, selected, disabled, and icon. selected is the resolved option list, so selected.length is the multi-select count. The default field props, including label, size, and status, do not apply to a custom trigger. state.icon contains the Select icon prop so the replacement trigger can display the same icon.

The second example uses a custom trigger and renderIndicator for a column visibility control. The options are column names. In this example, a selected option means that its column is hidden: the indicator changes from eye to eye-closed. The Tag uses selected.length, so it appears only after a column is hidden.

renderEmpty({ query }) renders content when the option list is empty after filtering. It can return a “No results” message, a loading indicator, or a row that creates an option from query. A non-empty query means that filtering removed every option; an empty query means that no options were supplied.

Select has no built-in empty message. If renderEmpty is omitted, an empty list has no content. Loading also belongs to application state, so return a 'Loading…' branch when that state is true.

The returned content replaces the option rows. A MenuSeparator with text is a muted caption and an aria-live="polite" region. Return a MenuItem, such as the Create "…" row, when the content must be selectable by keyboard.

An options entry is a plain option, a group ({ label, options }, an inline titled section), or a submenu ({ label, submenu }, a flyout). They nest and mix freely. Discriminated by shape — an options array is a group, a submenu array is a submenu, everything else is an option (so those two keys are reserved on an option).

Selection stays global. The Select’s selection (single / multiple) applies to every leaf wherever it sits; group headings and submenu parents organize but aren’t selectable. One value, one onValueChange, one count — unchanged. The two selects above share the exact same fields tree and differ only by selection. disabled on a group or submenu cascades to all its descendants. Because selection is global, a leaf’s value must be unique across the whole tree — the same value under two sections is one pick (dev builds warn).

A query flattens the tree. With filter, typing collapses submenus into inline groups (their label becomes the heading) and drops empty ones, so results read as one scannable list instead of hiding matches behind flyouts.