Tuimorphic

ComboBox

Autocomplete input combining text entry with dropdown selection and filtering.

Import

import { ComboBox } from 'tuimorphic';

Basic Usage

<ComboBox
  placeholder="Search countries..."
  options={[
    { value: 'us', label: 'United States' },
    { value: 'uk', label: 'United Kingdom' },
    { value: 'ca', label: 'Canada' },
  ]}
/>

Props

PropTypeDefaultDescription
options*ComboBoxOption[]Options to display in the dropdown
valuestringSelected value (controlled)
defaultValuestring''Default selected value (uncontrolled)
onValueChange(value: string) => voidCallback when value changes
placeholderstring'Search...'Placeholder text
labelstringLabel text
disabledbooleanfalseWhether the combobox is disabled
classNamestringAdditional CSS class names
refReact.Ref<HTMLInputElement>Forwarded ref to the input element

ComboBoxOption Type

interface ComboBoxOption {
  value: string;
  label: string;
  description?: string;
}

With Label

<ComboBox
  label="Country"
  placeholder="Search countries..."
  options={countries}
/>

With Descriptions

Options can include descriptions that are also searchable:

<ComboBox
  label="Country"
  placeholder="Search by name or region..."
  options={[
    { value: 'us', label: 'United States', description: 'North America' },
    { value: 'uk', label: 'United Kingdom', description: 'Europe' },
    { value: 'jp', label: 'Japan', description: 'Asia' },
  ]}
/>

States

<ComboBox label="Enabled" placeholder="Search..." options={options} />
<ComboBox label="Disabled" placeholder="Search..." options={options} disabled />

Default Value

<ComboBox
  label="Framework"
  defaultValue="React"
  options={frameworks}
/>

Controlled ComboBox

Value: (empty)
const [value, setValue] = useState('');
 
<ComboBox
  label="Framework"
  placeholder="Search frameworks..."
  options={frameworks}
  value={value}
  onValueChange={setValue}
/>

Interactive Example

Country: (none)

Framework: (none)

const [country, setCountry] = useState('');
const [framework, setFramework] = useState('');
 
<ComboBox
  label="Country"
  placeholder="Search countries..."
  options={countries}
  value={country}
  onValueChange={setCountry}
/>
<ComboBox
  label="Favorite Framework"
  placeholder="Search frameworks..."
  options={frameworks}
  value={framework}
  onValueChange={setFramework}
/>

Long Option List

Works well with many options:

<ComboBox
  label="Country"
  placeholder="Type to filter 40+ countries..."
  options={allCountries}
/>

Features

  • Autocomplete filtering: Type to filter options
  • Highlight matching text: Matching portions are highlighted
  • Keyboard navigation: Full keyboard support
  • Descriptions: Optional description field for each option
  • Click or type: Open dropdown by clicking arrow or typing

Keyboard Navigation

KeyAction
Arrow DownOpen dropdown / highlight next option
Arrow UpHighlight previous option
EnterSelect highlighted option
EscapeClose dropdown
TabClose dropdown and move focus

Accessibility

  • Proper ARIA combobox attributes
  • Screen reader support
  • Full keyboard navigation
  • Focus management

Styling

VariableDescription
--theme-borderInput and dropdown border
--theme-backgroundInput and dropdown background
--theme-textText color
--theme-buttonHighlighted option background
  • Select - For non-searchable dropdowns
  • Input - For free-form text entry

On this page