Combobox

Navigation

Stablev1.0.0

Searchable select with autocomplete functionality, built on Ariakit for accessibility.

Preview

Installation

pnpm add @component-labs/ui

Usage

import { Combobox } from "@component-labs/ui";

const options = [
  { value: "apple", label: "Apple" },
  { value: "banana", label: "Banana" },
];

<Combobox options={options} placeholder="Select fruit..." />

Props

Name	Type	Default	Description
`options*`	`ComboboxOption[]`	`-`	Array of options to display in the dropdown
`variant`	`'default' \| 'outline'`	`'default'`	Visual style variant
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	Size of the input
`label`	`string`	`-`	Label text above the combobox
`placeholder`	`string`	`-`	Placeholder text for the input
`showClear`	`boolean`	`true`	Show clear button when value is not empty
`filterFn`	`(options: ComboboxOption[], searchValue: string) => ComboboxOption[]`	`-`	Custom filter function for options
`onValueChange`	`(value: string) => void`	`-`	Callback when search value changes
`onSelectOption`	`(value: string) => void`	`-`	Callback when an option is selected
`emptyMessage`	`string`	`'No results found'`	Message to display when no results found
`renderItem`	`(option: ComboboxOption) => ReactNode`	`-`	Custom render function for items

Examples

Basic Combobox

Simple searchable select

const fruits = [
  { value: "apple", label: "Apple" },
  { value: "banana", label: "Banana" },
  { value: "orange", label: "Orange" },
];

<Combobox
  label="Select a fruit"
  placeholder="Search fruits..."
  options={fruits}
/>

With Custom Filter

Using custom filter logic

const customFilter = (options, search) => {
  return options.filter(opt =>
    opt.label.toLowerCase().startsWith(search.toLowerCase())
  );
};

<Combobox
  options={fruits}
  filterFn={customFilter}
  placeholder="Type to search..."
/>

Controlled Selection

Handle selection changes

const [selected, setSelected] = useState("");

<Combobox
  options={fruits}
  onSelectOption={(value) => {
    setSelected(value);
    console.log("Selected:", value);
  }}
  placeholder="Choose..."
/>

Custom Item Rendering

Customize how items are rendered

<Combobox
  options={users}
  renderItem={(option) => (
    <div className="flex items-center gap-2">
      <Avatar src={option.avatar} />
      <span>{option.label}</span>
    </div>
  )}
/>

Performance

Bundle Size

~5kB gzipped

Minified and gzipped

Dependencies

•@ariakit/react
•class-variance-authority

Accessibility

•Built on Ariakit's accessible Combobox component
•Keyboard navigation (Arrow keys, Enter, Escape)
•Proper ARIA attributes (aria-autocomplete, aria-expanded)
•Screen reader support with announcements
•Focus management
•Type-ahead functionality