Combobox
Searchable combobox component with filtering, keyboard navigation, and accessibility for advanced option selection
Installation
Install the Combobox component using the nocta-ui CLI:
npx nocta-ui add comboboxImport the component:
import { Combobox, ComboboxOption } from '@/components/ui/combobox';Examples
The Combobox component provides a searchable dropdown interface for selecting from a list of options.
Variants
The Combobox component supports three visual variants: default, error, and success.
This field is required
Selection confirmed
Sizes
Three size options are available: sm, md, and lg. The default size is md.
Clearable Selection
Control whether users can clear their selection with an X button.
X button appears when value is selected
No clear button shown
Disabled Options
Individual options can be disabled by setting the disabled property.
Some options are disabled (e.g., PHP)
Disabled State
The entire combobox can be disabled.
Entire combobox is disabled
Custom Messages
Customize the empty state message when no options match the search.
Type something that doesn't match to see custom message
Controlled vs Uncontrolled
Uncontrolled (Recommended)
Use defaultValue for uncontrolled behavior:
<Combobox
options={options}
defaultValue="react"
onValueChange={(value) => console.log('Selected:', value)}
/>Controlled
Use value and onValueChange for controlled behavior:
Current value: react
Api Reference
Combobox
| Prop | Type | Default | Description |
|---|---|---|---|
options | ComboboxOption[] | — | Array of selectable options |
value | string | — | Controlled selected value |
defaultValue | string | — | Default selected value |
onValueChange | (value: string) => void | — | Callback when selection changes |
portal | boolean | true | Render the combobox in a React portal |
placeholder | string | 'Select option...' | Placeholder text |
searchPlaceholder | string | 'Search...' | Search input placeholder |
emptyMessage | string | 'No options found' | Message when no options match |
disabled | boolean | false | Disable the combobox |
size | 'sm' | 'md' | 'lg' | 'md' | Size variant |
variant | 'default' | 'error' | 'success' | 'default' | Visual variant |
className | string | '' | Additional CSS classes for trigger |
popoverClassName | string | '' | Additional CSS classes for dropdown |
clearable | boolean | true | Show clear button when value selected |
ComboboxOption
| Prop | Type | Default | Description |
|---|---|---|---|
value | string | — | Unique option identifier |
label | string | — | Display text for the option |
disabled | boolean | false | Disable this option |
The Combobox component also accepts all standard HTML button attributes for the trigger element.