Skip to content

Select

⋯

Select wraps Base UI’s single-value listbox with a field label, help text, and validation message. Its trigger and popup use Nesra semantic tokens in the supported light theme. Figma’s Filters composition includes select-like controls, but it does not define a generic Select component. This is a reusable primitive inspired by Kumo UI’s field API, without claiming exact Figma parity.

Import Select from @nesra/ui/select or @nesra/ui. items maps submitted string values to visible labels and creates the options.

import { Select } from "@nesra/ui/select";
export function FruitChoice() {
return (
<Select
label="Fruit"
name="fruit"
placeholder="Choose a fruit"
items={{ apple: "Apple", cherry: "Cherry" }}
/>
);
}

Use Select.Option as children when options need custom markup or individual disabled states. Keep items to map submitted values to trigger labels, or provide renderValue. When there is no visible label, provide aria-label.

import { Select } from "@nesra/ui/select";
export function FruitChoice() {
return (
<Select
aria-label="Fruit"
placeholder="Choose a fruit"
items={{ apple: "Apple", banana: "Banana" }}
>
<Select.Option value="apple">Apple</Select.Option>
<Select.Option value="banana" disabled>
Banana (unavailable)
</Select.Option>
</Select>
);
}

The page owns value and updates it through onValueChange. A disabled option remains visible but cannot be chosen.

Selected: none

Provide aria-label when the surrounding layout supplies enough visual context.

description renders help text below the trigger.

Choose the category that best describes the issue.

An external error replaces the description and gives the trigger the destructive border and ring. The application decides when to set it. Colors follow the field state colors in Light and Dark. A disabled trigger keeps the neutral surface and uses text-disabled and icon-disabled.

The placeholder is shown while no value is selected.

Select.Option accepts custom content. renderValue formats the selected string in the trigger when there is no items mapping.

The first list has an unavailable option. The second trigger is disabled.

side, align, and sideOffset change the preferred popup position. Base UI can adjust placement when space is limited.

name supplies the submitted string value. required asks the browser to block submission while empty.

The popup scrolls when its options exceed the available height.

Open the list to scroll through 30 options.

Use Select.Group and Select.GroupLabel to organize related options. Select.Separator adds a visual divider between groups. Supply items to show each selected option’s label in the trigger.

Base UI provides combobox and listbox roles, arrow-key navigation, typeahead, Escape dismissal, and focus return. label gives the trigger an accessible name. When omitting it, set aria-label. name adds the selected string to form submission. required prevents submission while empty. error replaces description and exposes the message to assistive technology. The consuming form owns validation logic and error timing. Select is single-value and has no search field.

Prop Type Default Effect
items Record<string, string> — Creates options when children is absent and maps values to labels.
children Select.Option or groups — Provides custom options instead of generated items.
label ReactNode — Renders a visible associated label.
aria-label string — Names the trigger when label is absent.
description ReactNode — Shows help text below the trigger.
error FieldError — Replaces help text with a validation message.
placeholder ReactNode Select an option Shows text while empty.
renderValue (value: string) => ReactNode — Formats a selected value.
value string | null — Controls the selected value.
defaultValue string | null — Sets an initial uncontrolled value.
onValueChange (value, details) => void — Reports a selection change.
name string — Names the submitted form field.
required boolean false Requires a selection for form submission.
disabled boolean false Prevents interaction.
side, align, sideOffset Base UI Positioner props bottom, center, 4 Positions the popup. Offset is in pixels.
className string — Styles the field container.
triggerClassName, contentClassName string — Styles the trigger and popup.

The component also forwards Base UI Select root props for open state, form ownership, and autofill. It accepts one string value. Search and multiple selection are outside this contract.

value is a required unique string. Forwards Base UI Item props including disabled, label, className, and ref. The option text and selected check mark are included.

Select.Group, Select.GroupLabel, Select.Separator

Section titled “Select.Group, Select.GroupLabel, Select.Separator”

Select.Group wraps related options. Put one Select.GroupLabel inside each group to name it accessibly. Add Select.Separator between groups when a visual divider helps. These parts forward their corresponding Base UI props, including className and ref.