Forms

Combobox

Typeahead-search select that pairs a Popover trigger with a Command palette listbox.

Preview
01 Installation

Install

Pull Combobox from the barrel for everyday use, or the granular path when you want a tighter bundle.

tsxBarrel1 line
import { Combobox } from "@brika/clay";
tsxGranular1 line
import { Combobox } from "@brika/clay/components/combobox";
02 Usage

A minimal example

Drop this into a page. Native HTML attributes pass through to the underlying primitive.

tsxCombobox.tsx25 lines
'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>
  );
}
03 Examples

Combobox, every way

Controlled

Controlled combobox, drives state with `useState` and reflects the current selection below the trigger.

Form

Combobox with `name="framework"` inside a `<form>`, the hidden input lets native form submission carry the value.

04 Accessibility

Accessibility

  • Trigger button advertises role="combobox" and aria-expanded so 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.
05 Tokens 2 theme-overridable

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
ColorFill, border, and text colors.2
  • --combobox-trigger-placeholder-colorcolorvar(--muted-foreground)
    components.combobox.triggerPlaceholderColor

    Foreground color of the placeholder rendered inside the trigger button when no value is selected.

  • --combobox-selected-icon-colorcolorvar(--foreground)
    components.combobox.selectedIconColor

    Color 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.

jsonmy-theme.json12 lines
{
  "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.

06 API reference

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.
  • string
    Accessible name for the trigger; defaults to the resolved label or placeholder.
  • string
    Forwarded to the trigger button for layout overrides.
  • string
    Forwarded to the popover content for width or alignment overrides.
  • boolean
    Initial open state for the popover (uncontrolled).
  • string
    Initial selected value for uncontrolled mode.
  • boolean
    Disable the trigger entirely.
  • emptyTextdefault 'No results found.'
    string
    Copy shown when the typeahead returns no matches.
  • boolean
    Render the trigger as wide as its parent.
  • string
    Form field name; emitted alongside the trigger for native form submission.
  • (open: boolean) => void
    Called whenever the popover opens or closes.
  • (value: string) => void
    Called with the next value whenever the user picks an option. Pass the same value to clear.
  • boolean
    Controlled open state for the popover; pair with onOpenChange.
  • placeholderdefault 'Select option...'
    string
    Text shown inside the trigger when nothing is selected.
  • searchPlaceholderdefault 'Search...'
    string
    Placeholder for the search input inside the popover.
  • sizedefault 'default'
    'sm' | 'default' | 'lg'
    Trigger size preset, mirrors <Button size>.
  • string
    Controlled selected value; pair with onValueChange.