Stepwise UI

Combobox

A dropdown you can type into. Filters as you type, highlights the matched text, and is fully keyboard-driven. The field matches the Input's squircle and border treatment, so it sits naturally in a form.

Installation

npx stepwise-ui add combobox

Default

Each option can carry an optional description - it's searched alongside the label.
import { Combobox } from '@/components/stepwise/combobox'

const options = [
  { value: 'next',  label: 'Next.js', description: 'The React framework for the web' },
  { value: 'remix', label: 'Remix',   description: 'Full stack web framework' },
]

<Combobox
  label="Framework"
  options={options}
  value={value}
  onChange={setValue}
  placeholder="Search frameworks…"
/>

Without descriptions

// Descriptions are optional - omit them for a compact list
const countries = [
  { value: 'in', label: 'India' },
  { value: 'us', label: 'United States' },
]

<Combobox label="Country" options={countries} value={v} onChange={setV} />

Empty state

<Combobox
  options={countries}
  emptyMessage="Nothing matches that search"
/>

Keyboard

  • ↓ / ↑ - move through the filtered options (wraps around).
  • Enter - select the highlighted option.
  • Esc - close the list and clear the query.
  • Typing filters instantly; the matched substring is emphasised in each row.

Props

PropTypeDescription
options
ComboboxOption[]
Array of { value, label, description? }.
value
string
Controlled selected value.
onChange
(value: string) => void
Called when an option is chosen.
placeholder
string
Field placeholder. Default "Search…".
label
string
Label rendered above the field.
emptyMessage
string
Shown when nothing matches. Default "No results found".
disabled
boolean
Disables the field.