Combobox
Combobox filters one bounded synchronous option set and commits one form-backed value while data orchestration remains consumer-owned.
Overview and decision boundary
Use Combobox when one value must be selected from a bounded synchronous set that benefits from filtering.
Do not add remote fetching, debounce, ranking, creation, virtualization, multiple selection, routing, analytics, or persistence.
Filter the supported destinations and choose one value.
import { Combobox } from '@nerio-ui/ui/client';<Combobox label="City" name="city" options={[ { value: 'paris', label: 'Paris', textValue: 'Paris' }, { value: 'tbilisi', label: 'Tbilisi', textValue: 'Tbilisi' }, { value: 'tokyo', label: 'Tokyo', textValue: 'Tokyo' }, ]}/>Installation and imports
Install the editable registry source, or use the matching package entrypoint when the product keeps Nerio as a workspace dependency.
pnpm exec nerio add comboboximport { Combobox } from '@nerio-ui/ui/client';Usage
import { Combobox } from '@nerio-ui/ui/client';<Combobox label="City" name="city" options={[ { value: 'paris', label: 'Paris', textValue: 'Paris' }, { value: 'tbilisi', label: 'Tbilisi', textValue: 'Tbilisi' }, { value: 'tokyo', label: 'Tokyo', textValue: 'Tokyo' }, ]}/>Variants
| Variant | Purpose |
|---|---|
options | Options is part of the public component contract. |
composed | Composed is part of the public component contract. |
flat | Flat is part of the public component contract. |
grouped | Grouped is part of the public component contract. |
sm | Compact size for dense layouts and inline use. |
md | Default size for most product surfaces. |
lg | Larger size for prominent local actions. |
RTL | RTL is part of the public component contract. |
Anatomy
| Slot | Purpose |
|---|---|
root | Field root with stable state and size hooks. |
label | Visible native label for the editable combobox input. |
input-group / input | Query input with clear and popup actions. |
trigger / icon | Localizable popup toggle and direction-aware chevron. |
content / list | Anchored, collision-aware filtered listbox. |
item / item-description | Selectable option with optional supporting text. |
indicator | Selected-item check indicator. |
group / group-label | Labelled grouping for related options. |
empty / loading | Polite presentation regions that remain mounted. |
description / message | Associated help or validation content. |
States
| State | Behavior |
|---|---|
Query | Filters the supplied synchronous items without changing selection. |
Open | Shows the filtered list while focus remains on the input. |
Highlighted / selected | Separates the next keyboard target from the committed value. |
Empty / loading | Displays consumer-provided presentation without owning fetching. |
Disabled / read-only | Prevents interaction while preserving truthful semantics. |
Required / invalid | Participates in forms and associates validation content. |
Motion
- overlay entry and exit
- reduced-motion immediate transition
Accessibility
- Uses the Base UI Combobox primitive with a native visible label and active-descendant listbox navigation.
- Query, selected value, and popup state each support independent controlled and uncontrolled ownership without mirrored state.
- Options require stable unique generic string values and explicit textValue strings for filtering, input display, and accessible identity.
- Arrow keys navigate enabled options, Enter commits one value, Escape closes, pointer selection retains input focus, and disabled options are skipped.
- Description and message content are associated with the input; invalid messages use alert semantics only when invalid is true.
- Clear and popup actions have localizable accessible names through clearLabel and toggleLabel.
- Empty and loading presentation use dedicated polite regions that remain mounted.
- Name, form, required, autoComplete, disabled, readOnly, and native form reset are supported.
- Pair document dir with Base UI DirectionProvider and localize visible text plus action labels for RTL and non-English products.
- Fetching, debounce, ranking, creation, virtualization, multiple selection, routing, analytics, persistence, and business validation remain consumer or Pro responsibilities.
Review the shared responsibility and evidence boundaries in the Accessibility foundation alongside this component-specific contract. Use the Spacing & layout foundation for shared density, wrapping, overflow, reflow, and component-versus-product ownership guidance. The Color foundation, Typography foundation, and Localization foundation define the shared visual-role, text-resilience, direction, and locale boundaries used by component examples.
API
| Props | Purpose |
|---|---|
options | Flat or grouped data with generic string values, textValue, labels, descriptions, and disabled state. |
items / children | The same item data paired with curated ComboboxItem composition. |
query / defaultQuery / onQueryChange | Independent controlled or uncontrolled input query. |
value / defaultValue / onValueChange | Independent controlled or uncontrolled selected value. |
open / defaultOpen / onOpenChange | Independent controlled or uncontrolled popup state. |
filter / locale | Consumer filter override, no filtering with false, or locale-aware contains matching by default. |
loading / emptyMessage / loadingMessage | Presentation only; consumers own loading and data orchestration. |
name / form / required / autoComplete | Form identity, ownership, required state, reset, and autofill hint. |
clearLabel / toggleLabel | Localizable names for icon-only actions. |
Implementation contract
| Contract | Value |
|---|---|
Registry item | combobox installs 11 source files into the configured components directory. |
Base UI | combobox |
Registry dependencies | form-message, spinner |
Package dependencies | @base-ui/react, @nerio-ui/adapters, clsx, react, tailwind-merge, tailwindcss |
Styling contract
| Contract | Value |
|---|---|
Authoring | Complete, statically detectable Tailwind CSS v4 recipes own component visuals. |
Values | Semantic and component --n-* variables remain the canonical customization layer. |
Overrides | Customizable slots merge consumer className values with tailwindCn so conflicting utilities resolve deterministically. |
Residual CSS | Only shared keyframes and scoped no-Preflight compatibility rules remain; there is no parallel visual selector layer. |
Design notes
- Use Combobox when one value must be selected from a bounded synchronous set that benefits from filtering.
Do / do not
Do
Use for one selected value from a bounded synchronous set that benefits from filtering.
Do not
Put fetching, debounce, ranking, creation, virtualization, multiple selection, routing, analytics, or persistence in Combobox.
Related components
Tokens
These are the primary customization points. Override semantic or component tokens instead of changing component source.
| Token | Purpose |
|---|---|
--n-select-height-sm | Public customization point for this component contract. |
--n-select-height-md | Public customization point for this component contract. |
--n-select-height-lg | Public customization point for this component contract. |
--n-select-padding-inline | Public customization point for this component contract. |
--n-select-item-gap | Public customization point for this component contract. |
--n-select-item-padding-inline | Public customization point for this component contract. |
--n-select-group-label-padding-inline | Public customization point for this component contract. |
--n-select-empty-padding | Public customization point for this component contract. |
--n-select-popup-radius | Public customization point for this component contract. |
--n-input-radius | Public customization point for this component contract. |
--n-input-background | Public customization point for this component contract. |
--n-input-border | Public customization point for this component contract. |
--n-input-border-hover | Public customization point for this component contract. |
--n-input-border-danger | Public customization point for this component contract. |
--n-input-placeholder | Public customization point for this component contract. |
--n-input-foreground | Public customization point for this component contract. |
--n-input-disabled-background | Public customization point for this component contract. |
--n-input-disabled-foreground | Public customization point for this component contract. |
--n-overlay-floating-z-index | Public customization point for this component contract. |
--n-overlay-background | Public customization point for this component contract. |
--n-overlay-border | Public customization point for this component contract. |
--n-overlay-shadow | Public customization point for this component contract. |
--n-focus-ring | Public customization point for this component contract. |