Combobox

Searchable select. Free, MIT · Forms and input › Selects

Editable combobox with list autocomplete. Props not listed go to the <input>; name submits the value.

Installation

npx valyro-cli@latest add combobox

npx shadcn@latest add https://valyro.xyz/r/combobox.json

npm install valyro-ui

import 'valyro-ui/styles.css';
import { Combobox } from 'valyro-ui';

Props

Prop	Type	Default
`options`	`SelectItem[]`		Suggestions, flat or in labelled groups; filtered by the typed text unless `filter={false}`. Or compose them as children: `Combobox.Item`, `Combobox.Group`, `Combobox.Empty`.
`children`	`ReactNode`		The compound form instead of `options`: `Combobox.Item`, `Combobox.Group` and `Combobox.Empty` elements.
`value`	`string`		Selected option value (or the typed text with `allowCustomValue`); empty string means none.
`defaultValue`	`string`		Initial `value` when uncontrolled.
`onValueChange`	`(value: string) => void`		Called with the new `value` when it changes.
`inputValue`	`string`		Text in the input. Control it together with `filter={false}` to load options asynchronously.
`defaultInputValue`	`string`		Initial `inputValue` when uncontrolled.
`onInputValueChange`	`(text: string) => void`		Called with the text whenever the input changes (typing, picking an option, clearing).
`open`	`boolean`		Controlled `open`; use with `onOpenChange`.
`defaultOpen`	`boolean`		Initial `open` when uncontrolled.
`onOpenChange`	`(open: boolean) => void`		Called with the new `open` when it changes.
`filter`	`false \| ((option: SelectOption, query: string) => boolean)`		Custom matcher, or `false` when `options` are already filtered (e.g. by a server). Default: the label contains the text, ignoring case and accents for the ThemeProvider locale ("e" finds "é", as React Aria's useFilter).
`loading`	`boolean`	`false`	Shows a spinner in the field, sets aria-busy, and replaces the empty state with a loading message.
`emptyText`	`ReactNode`		Shown in the popover when no option matches (unless `allowCustomValue` offers the typed text). Or `Combobox.Empty`.
`labels`	`Partial<ComboboxLabels>`		Overrides for the built-in English text; keys left out keep their defaults.
`allowCustomValue`	`boolean`	`false`	Typed text that matches no option is kept as the value on Enter / blur.
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	Field height and text size.
`invalid`	`boolean`	`false`	Error border and aria-invalid on the input (an explicit `aria-invalid` wins).
`leftIcon`	`ReactNode`		Icon inside the field, before the text.

Compound parts

Combobox.Item (ComboboxItem), Combobox.Group (ComboboxGroup), Combobox.Empty (ComboboxEmpty)

Related components

Select — Pick one option from a list
Multi Select — Pick several options
Listbox — Option list on the page: one or several, Shift ranges
Chip Group — Chip group with icons: one or several options
Checkbox Tree — Checkbox tree: cascading, indeterminate state, keyboard
Text Input — Text fields
Textarea — Multiline text input
Search Input — Search field
Mentions Input — Text with @mentions and #tags, async suggestions
Tags Input — Tag entry
Checkbox — Checkboxes
Checkbox Group — Checkboxes under one label, hint, error and requirement

Previous: Multi Select · Next: Listbox · All Forms and input