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" }} /> );}Composition
Section titled “Composition”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> );}Examples
Section titled “Examples”import { Select } from "@nesra/ui/select";
const items = { apple: "Apple", banana: "Banana", cherry: "Cherry" };
export function BasicSelectExample() { return ( <Select className="w-full max-w-72" label="Fruit" name="fruit" items={items} defaultValue="apple" /> );}Controlled and disabled option
Section titled “Controlled and disabled option”The page owns value and updates it through onValueChange. A disabled option remains visible but
cannot be chosen.
import { Select } from "@nesra/ui/select";import { useState } from "react";
export function ControlledSelectExample() { const [value, setValue] = useState<string | null>(null); return ( <div className="w-full max-w-72"> <Select label="Fruit" placeholder="Choose a fruit" items={{ apple: "Apple", banana: "Banana", cherry: "Cherry" }} value={value} onValueChange={setValue} > <Select.Option value="apple">Apple</Select.Option> <Select.Option value="banana" disabled> Banana (unavailable) </Select.Option> <Select.Option value="cherry">Cherry</Select.Option> </Select> <p className="mt-2 type-nesra-body-small-regular">Selected: {value ?? "none"}</p> </div> );}Without a visible label
Section titled “Without a visible label”Provide aria-label when the surrounding layout supplies enough visual context.
import { Select } from "@nesra/ui/select";
export function SelectWithoutLabelExample() { return ( <Select aria-label="Favorite fruit" className="w-full max-w-72" defaultValue="apple" items={{ apple: "Apple", banana: "Banana", cherry: "Cherry" }} /> );}Description
Section titled “Description”description renders help text below the trigger.
import { Select } from "@nesra/ui/select";
export function SelectDescriptionExample() { return ( <Select className="w-full max-w-72" label="Issue type" description="Choose the category that best describes the issue." items={{ bug: "Bug", documentation: "Documentation", feature: "Feature request" }} /> );}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.
import { Select } from "@nesra/ui/select";
export function SelectErrorExample() { return ( <Select className="w-full max-w-72" label="Issue type" description="Choose a category." error="Select an issue type before continuing." items={{ bug: "Bug", documentation: "Documentation", feature: "Feature request" }} required /> );}Placeholder
Section titled “Placeholder”The placeholder is shown while no value is selected.
import { Select } from "@nesra/ui/select";
export function SelectPlaceholderExample() { return ( <Select className="w-full max-w-72" label="Category" placeholder="Choose a category..." items={{ analytics: "Analytics", billing: "Billing", security: "Security" }} /> );}Custom option display
Section titled “Custom option display”Select.Option accepts custom content. renderValue formats the selected string in the trigger
when there is no items mapping.
import { Select } from "@nesra/ui/select";
const languages = { en: "🇬🇧 English", id: "🇮🇩 Indonesian", ja: "🇯🇵 Japanese" };
export function SelectCustomRenderingExample() { return ( <Select className="w-full max-w-72" label="Language" defaultValue="id" renderValue={(value) => languages[value as keyof typeof languages]} > <Select.Option value="en">🇬🇧 English</Select.Option> <Select.Option value="id">🇮🇩 Indonesian</Select.Option> <Select.Option value="ja">🇯🇵 Japanese</Select.Option> </Select> );}Disabled select and option
Section titled “Disabled select and option”The first list has an unavailable option. The second trigger is disabled.
import { Select } from "@nesra/ui/select";
export function SelectDisabledExample() { return ( <div className="grid w-full max-w-72 gap-4"> <Select label="Available options" defaultValue="apple" items={{ apple: "Apple", banana: "Banana", cherry: "Cherry" }} > <Select.Option value="apple">Apple</Select.Option> <Select.Option value="banana" disabled> Banana (unavailable) </Select.Option> <Select.Option value="cherry">Cherry</Select.Option> </Select> <Select label="Disabled select" defaultValue="apple" items={{ apple: "Apple" }} disabled /> </div> );}Placement
Section titled “Placement”side, align, and sideOffset change the preferred popup position. Base UI can adjust placement
when space is limited.
import { Select } from "@nesra/ui/select";
const planets = { earth: "Earth", mars: "Mars", venus: "Venus" };
export function SelectPlacementExample() { return ( <div className="grid w-full gap-4 sm:grid-cols-2"> <Select className="w-52" label="Below (default)" items={planets} defaultValue="earth" /> <Select className="w-52" label="Above" items={planets} defaultValue="earth" side="top" /> <Select className="w-52" label="End aligned" items={planets} defaultValue="earth" align="end" /> <Select className="w-52" label="12px offset" items={planets} defaultValue="earth" sideOffset={12} /> </div> );}Native form submission
Section titled “Native form submission”name supplies the submitted string value. required asks the browser to block submission while
empty.
import { Button } from "@nesra/ui/button";import { Select } from "@nesra/ui/select";import { useState, type SubmitEvent } from "react";
export function SelectFormExample() { const [submitted, setSubmitted] = useState<string | null>(null);
function handleSubmit(event: SubmitEvent<HTMLFormElement>) { event.preventDefault(); setSubmitted(String(new FormData(event.currentTarget).get("priority"))); }
return ( <form className="grid w-full max-w-72 gap-4" onSubmit={handleSubmit}> <Select label="Priority" name="priority" placeholder="Choose a priority" items={{ low: "Low", medium: "Medium", high: "High" }} required /> <Button type="submit">Submit</Button> {submitted && <p className="type-nesra-body-small-regular">Submitted value: {submitted}</p>} </form> );}Long list
Section titled “Long list”The popup scrolls when its options exceed the available height.
import { Select } from "@nesra/ui/select";
const items = Object.fromEntries( Array.from({ length: 30 }, (_, index) => [`option-${index + 1}`, `Option ${index + 1}`]),);
export function SelectLongListExample() { return ( <Select className="w-full max-w-72" label="Long list" description="Open the list to scroll through 30 options." placeholder="Choose an option..." items={items} /> );}Grouped options
Section titled “Grouped 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.
import { Select } from "@nesra/ui/select";
const foods = { apple: "Apple", banana: "Banana", carrot: "Carrot", spinach: "Spinach",};
export function SelectGroupedExample() { return ( <Select className="w-full max-w-72" label="Food" placeholder="Pick a food..." items={foods}> <Select.Group> <Select.GroupLabel>Fruits</Select.GroupLabel> <Select.Option value="apple">Apple</Select.Option> <Select.Option value="banana">Banana</Select.Option> </Select.Group> <Select.Separator /> <Select.Group> <Select.GroupLabel>Vegetables</Select.GroupLabel> <Select.Option value="carrot">Carrot</Select.Option> <Select.Option value="spinach">Spinach</Select.Option> </Select.Group> </Select> );}Accessibility
Section titled “Accessibility”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.
API reference
Section titled “API reference”Select
Section titled “Select”| 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.
Select.Option
Section titled “Select.Option”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.