Skip to content

Combobox

⋯

Combobox combines a searchable input, a filtered option list, and a single selected value. Its field and option styles use the same Nesra tokens as Input and Select.

Import Combobox from @nesra/ui/combobox or @nesra/ui. Each item needs a unique string value and a searchable label.

import { Combobox } from "@nesra/ui/combobox";
export function FruitChoice() {
return (
<Combobox
label="Fruit"
name="fruit"
items={[
{ value: "apple", label: "Apple" },
{ value: "banana", label: "Banana" },
]}
>
<Combobox.TriggerInput placeholder="Select a fruit" />
<Combobox.Content>
<Combobox.Empty>No fruit found</Combobox.Empty>
<Combobox.List />
</Combobox.Content>
</Combobox>
);
}
Combobox
├── TriggerInput (search in the field)
│ ├── input
│ ├── Clear
│ └── popup trigger
└── Content
├── Empty
└── List
└── Item

Combobox.List renders labeled items from items when no children are passed. Pass a render function to Combobox.List to customize Combobox.Item content. Each custom item’s value must match an entry in items. The item data supplies its search label and default disabled state.

For a select-like trigger, use Combobox.TriggerValue and put Combobox.Input inside Combobox.Content. Both compositions choose one value from items.

error replaces the description and gives the input wrapper or trigger the destructive border and ring. Colors follow the field state colors in Light and Dark.

Base UI supplies combobox and listbox semantics, keyboard navigation, filtering, and Escape dismissal. Combobox.TriggerInput keeps focus in the field during search. With Combobox.TriggerValue, opening the popup moves focus to Combobox.Input, and Escape returns it to the trigger. Provide a visible label or an aria-label on the input or trigger. The application owns validation logic and when to show an error.

Prop Type Default Effect
items readonly ComboboxItem[] required Supplies search labels and values. Values must be unique.
children ReactNode required Contains a trigger or input and popup content.
value, defaultValue string | null — Controls or initializes the selected value.
onValueChange Base UI Combobox callback — Reports selection changes.
name, required, disabled, readOnly inherited Base UI props — Set form and interaction behavior.
label, description ReactNode — Adds visible field text.
error FieldError — Replaces description with a validation message.
className string — Styles the field container.

ComboboxItem has required value and label strings and optional disabled. The root also forwards Base UI’s open, filter, and search input state props. Keep controlled values in items so their labels remain available.

Input trigger with a clear button and popup button. It accepts Base UI input props and forwards its ref to the input.

Prop Type Default Effect
placeholder string — Hints at the value to search or select.
showClear, showTrigger boolean true Show the clear and popup buttons.
clearLabel string Clear selection Names the clear button.
className, inputClassName string — Style the wrapper and input.

Combobox.TriggerValue accepts Base UI trigger props, placeholder (Select an option by default), and optional selected-value children. It forwards a button ref. Place Combobox.Input inside Combobox.Content for popup search. Combobox.Input accepts Base UI input props and forwards an input ref.

Popup container. It accepts Base UI popup props and forwards a popup ref.

Prop Type Default Effect
side, align, sideOffset Base UI positioner props bottom, start, 4 Place the popup.
container portal container document.body Selects the portal host.
className string or Base UI class callback — Styles the popup surface.

Combobox.List, Combobox.Item, and Combobox.Empty

Section titled “Combobox.List, Combobox.Item, and Combobox.Empty”

Combobox.List accepts Base UI list props. Without children, it renders one Combobox.Item per matching item in items. Its render function receives each matching ComboboxItem for custom markup. Combobox.Item requires a string value, inherits Base UI item props, and defaults disabled from the matching item data. Combobox.Empty accepts Base UI empty-state props and defaults its content to No options found. All three forward refs and accept className.

Combobox.Clear is also public. It accepts Base UI clear-button props, defaults its accessible label to Clear selection, and forwards a button ref.

See colors, typography, and accessibility for shared tokens and guidance.