Combobox

Installation

Import combobox primitives (and optionally ComboboxSelect) from @/components/kamod-ui/combobox.

pnpm add @kamod-ch/ui

The @/components/kamod-ui/… imports in these examples refer to local source files. Configure that alias when copying source, or use the corresponding exports from @kamod-ch/ui when installing the package. Connect the global theme CSS and Tailwind source detection before your first render.

Usage

Combobox supports single or multiple selection (value / onValueChange as string or string[]). liftedFilter shares the filter string between ComboboxInlineInput or ComboboxChipsInput and the list (Command stays mounted via forceMount on content). Set autoHighlight on the root (or ComboboxCommand) for first-match highlight plus ArrowUp/Down and Enter — works in ComboboxInput, ComboboxInlineInput, and ComboboxChipsInput via commandNavRef. showClear + ComboboxClear clears selection and filter. Multi-select: ComboboxChips + ComboboxChip + ComboboxChipsInput (implies liftedFilter). ComboboxSelect maps props to these patterns (liftedFilter, multiple, showClear, autoHighlight).

import { Combobox } from "@/components/kamod-ui/combobox";

Accessibility

Build the complete interaction, including the parts outside Combobox. The notes below distinguish the current implementation from the labels, content and behavior your application supplies. Start with the live preview, check the props and data reference, and test the finished composition with real content rather than assuming that an unchanged visual example covers every use case.

Verify the complete interaction

Check behavior as well as markup. Work through these scenarios in the application where the component will be used. Automated checks can help find structural problems; also review the reading experience with a screen reader, keyboard focus and the actual feedback from your application.

1. Search with the keyboard, select a result, reopen and clear the selection without losing the field label.
2. Remove a chip and verify focus goes to a surviving control with a meaningful name.
3. Test no matches, asynchronous results and disabled choices with your target screen reader.

Recheck the result after changing theme tokens, translations or class overrides. Include text enlargement, narrow layouts and reduced-motion settings where animation is present. Inspect the component source when a behavior differs from your expectation; a role or state attribute does not implement keyboard interaction by itself.

For background, read the WAI-ARIA authoring guidance and keyboard interface guidance. These explain the patterns; verify browser and assistive-technology behavior for the implementation and audience you actually support.

Build it into your interface

Use the Combobox examples as a starting point, then review the behavior in the context of your own screen. Layout, state and content should work together.

import type { ComponentChildren } from "preact";

export function ExampleSurface({ children }: { children: ComponentChildren }) {
  return (
    <div class="grid min-w-0 gap-4 rounded-lg border border-border bg-card p-4 text-card-foreground sm:p-6">
      {children}
    </div>
  );
}

Sources & design references

Follow Combobox from its implementation to the ideas behind your own composition. Start with the local API, explore a visual direction, then bring the result back to your app’s shared styles.