Combobox

Searchable single-select with type-to-filter, keyboard navigation, and custom rendering.

Combobox is a single-select that filters its options as the user types and is navigable with the arrow keys, Enter, and Escape. It is controlled: value holds the chosen option value (or null) and onChange reports changes. Each option is a ComboboxOption (value, label, optional description/icon). Filtering is built in, but pass onInputChange to drive remote search, and use renderOption for custom rows, clearable for a clear button, and loading to show a fetching state.

Example

Preview

import { Combobox } from '@officina/ui';
import { useState } from 'react';

function FruitPicker() {
  const [value, setValue] = useState<string | null>(null);
  return (
    <Combobox
      value={value}
      onChange={setValue}
      clearable
      placeholder="Search fruit…"
      options={[
        { value: 'apple', label: 'Apple' },
        { value: 'banana', label: 'Banana' },
        { value: 'cherry', label: 'Cherry' },
      ]}
    />
  );
}

API

Prop	Type	Default	Description
onChange*	(value: T \| null) => void	—	Called with the chosen value (or null when cleared).
options*	ComboboxOption<T>[]	—	Selectable options.
value*	T \| null	—	Currently selected value, or null.
clearable	boolean	true	Show a clear button to reset the selection.
disabled	boolean	—	Disables the input and prevents selection.
emptyMessage	string	No results	Message shown when no options match the query.
inputRef	Ref<HTMLInputElement>	—	Ref forwarded to the underlying text input.
invalid	boolean	—	Marks the field invalid for validation styling and `aria-invalid`.
loading	boolean	—	Show a loading state (e.g. while fetching options).
name	string	—	Form field name for the underlying input.
onInputChange	(q: string) => void	—	Called as the user types — use for async/remote filtering.
placeholder	string	—	Placeholder text for the input when nothing is selected.
renderOption	(option: ComboboxOption<T>) => ReactNode	—	Custom renderer for an option row.
required	boolean	—	Marks the field as required for validation styling and `aria-required`.
size	enum	md	Control size.

Example

API

On this page