Combobox
Typeahead-search select that pairs a Popover trigger with a Command palette listbox.
Install
Pull Combobox from the barrel for everyday use, or the granular path when you want a tighter bundle.
import { Combobox } from "@brika/clay";import { Combobox } from "@brika/clay/components/combobox";A minimal example
Drop this into a page. Native HTML attributes pass through to the underlying primitive.
'use client';
import { Combobox } from '@brika/clay/components/combobox';
const frameworks = [
{ value: 'next', label: 'Next.js' },
{ value: 'remix', label: 'Remix' },
{ value: 'astro', label: 'Astro' },
{ value: 'nuxt', label: 'Nuxt' },
{ value: 'svelte', label: 'Svelte' },
];
/** Uncontrolled combobox, picks a framework with typeahead search. */
export default function ComboboxDefaultDemo() {
return (
<div className="w-72">
<Combobox
options={frameworks}
placeholder="Select framework..."
searchPlaceholder="Search framework..."
emptyText="No framework found."
fullWidth
/>
</div>
);
}Combobox, every way
Accessibility
- Trigger button advertises
role="combobox"andaria-expandedso AT users hear the open/closed state. - When no value is selected, the trigger renders the placeholder using the muted-foreground slot for sufficient contrast.
- The active selection is announced inside the listbox via a leading check icon, mirrored in the trigger label.
Theme tokens
Every CSS variable Combobox reads, with its default and the
dotted path you'd write in a ThemeConfig JSON
to override it. Set any of these in your theme to retune Combobox
without touching component code.
Combobox tokens
2 tokens--combobox-trigger-placeholder-colorcolorvar(--muted-foreground)components.combobox.triggerPlaceholderColorForeground color of the placeholder rendered inside the trigger button when no value is selected.
--combobox-selected-icon-colorcolorvar(--foreground)components.combobox.selectedIconColorColor of the check icon shown next to the currently selected option inside the listbox.
Override in a theme
Authoring a theme is plain JSON. Drop overrides under
components.combobox, the names
are camelCase versions of the variable suffix.
{
"id": "my-theme",
"name": "My Theme",
"description": "...",
"accentSwatches": ["#000"],
"components": {
"combobox": {
"triggerPlaceholderColor": "var(--muted-foreground)"
}
}
}
Then apply with applyTheme(myTheme)
(see the theming guide),
scope it to a subtree with themeToCssVars(myTheme, mode),
or consume any token directly in your own JSX with the matching Tailwind utility
(e.g. bg-combobox-…) — see the
chips on each token row.
API reference
Props specific to Combobox. Native HTML attributes pass through to the underlying primitive, see the component source on GitHub for the full type signature.
- ComboboxOption[]Selectable options rendered inside the listbox.
- stringAccessible name for the trigger; defaults to the resolved label or placeholder.
- stringForwarded to the trigger button for layout overrides.
- stringForwarded to the popover content for width or alignment overrides.
- booleanInitial open state for the popover (uncontrolled).
- stringInitial selected value for uncontrolled mode.
- booleanDisable the trigger entirely.
- emptyTextdefault
'No results found.'stringCopy shown when the typeahead returns no matches. - booleanRender the trigger as wide as its parent.
- stringForm field name; emitted alongside the trigger for native form submission.
- (open: boolean) => voidCalled whenever the popover opens or closes.
- (value: string) => voidCalled with the next value whenever the user picks an option. Pass the same value to clear.
- booleanControlled open state for the popover; pair with
onOpenChange. - placeholderdefault
'Select option...'stringText shown inside the trigger when nothing is selected. - searchPlaceholderdefault
'Search...'stringPlaceholder for the search input inside the popover. - sizedefault
'default''sm' | 'default' | 'lg'Trigger size preset, mirrors<Button size>. - stringControlled selected value; pair with
onValueChange.