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> );}Composition
Section titled “Composition”Combobox├── TriggerInput (search in the field)│ ├── input│ ├── Clear│ └── popup trigger└── Content ├── Empty └── List └── ItemCombobox.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.
Examples
Section titled “Examples”import { Combobox } from "@nesra/ui/combobox";
const fruits = [ { value: "apple", label: "Apple" }, { value: "banana", label: "Banana" }, { value: "cherry", label: "Cherry" },];
export function BasicComboboxExample() { return ( <Combobox className="w-72 max-w-full" label="Fruit" name="fruit" items={fruits}> <Combobox.TriggerInput placeholder="Select a fruit" /> <Combobox.Content> <Combobox.Empty>No fruit found</Combobox.Empty> <Combobox.List /> </Combobox.Content> </Combobox> );}Controlled
Section titled “Controlled”import { Combobox } from "@nesra/ui/combobox";import { useState } from "react";
const fruits = [ { value: "apple", label: "Apple" }, { value: "banana", label: "Banana" }, { value: "cherry", label: "Cherry" },];
export function ControlledComboboxExample() { const [value, setValue] = useState<string | null>("apple"); return ( <Combobox className="w-72 max-w-full" label="Fruit" items={fruits} value={value} onValueChange={setValue} > <Combobox.TriggerInput placeholder="Select a fruit" /> <Combobox.Content> <Combobox.Empty>No fruit found</Combobox.Empty> <Combobox.List /> </Combobox.Content> </Combobox> );}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.
import { Combobox } from "@nesra/ui/combobox";
const fruits = [ { value: "apple", label: "Apple" }, { value: "banana", label: "Banana" }, { value: "cherry", label: "Cherry" },];
export function ErrorComboboxExample() { return ( <Combobox className="w-72 max-w-full" label="Fruit" name="fruit" items={fruits} error="Choose a fruit from the list." required > <Combobox.TriggerInput placeholder="Select a fruit" /> <Combobox.Content> <Combobox.Empty>No fruit found</Combobox.Empty> <Combobox.List /> </Combobox.Content> </Combobox> );}Custom items
Section titled “Custom items”import { Combobox } from "@nesra/ui/combobox";
const fruits = [ { value: "apple", label: "Apple" }, { value: "banana", label: "Banana" }, { value: "cherry", label: "Cherry", disabled: true },];
export function CustomComboboxOptionsExample() { return ( <Combobox className="w-72 max-w-full" label="Fruit" items={fruits}> <Combobox.TriggerInput placeholder="Select a fruit" /> <Combobox.Content> <Combobox.Empty>No fruit found</Combobox.Empty> <Combobox.List> {(fruit) => ( <Combobox.Item key={fruit.value} value={fruit.value}> Fresh {fruit.label} </Combobox.Item> )} </Combobox.List> </Combobox.Content> </Combobox> );}Search in the popup
Section titled “Search in the popup”import { Combobox } from "@nesra/ui/combobox";
const fruits = [ { value: "apple", label: "Apple" }, { value: "banana", label: "Banana" }, { value: "cherry", label: "Cherry" },];
export function PopupSearchComboboxExample() { return ( <Combobox className="w-72 max-w-full" label="Fruit" items={fruits}> <Combobox.TriggerValue placeholder="Select a fruit" /> <Combobox.Content> <Combobox.Input placeholder="Search fruit" /> <Combobox.Empty>No fruit found</Combobox.Empty> <Combobox.List /> </Combobox.Content> </Combobox> );}Accessibility
Section titled “Accessibility”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.
API reference
Section titled “API reference”Combobox
Section titled “Combobox”| 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.
Combobox.TriggerInput
Section titled “Combobox.TriggerInput”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 and Combobox.Input
Section titled “Combobox.TriggerValue and Combobox.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.
Combobox.Content
Section titled “Combobox.Content”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.