Cognition

Components

Combobox

A searchable select. It pairs a text input with a dropdown list so the reader can filter by typing, which keeps long option sets manageable.

Combobox is a higher-order component, composed from the Command and Popover primitives. The Popover positions the list; Command supplies the search input, filtering, and keyboard navigation.

Preview

Rendered with live Cognition tokens. Open it and type to filter, no dark: classes.

Variants

<Combobox options={regions} />
// options have a group field
<Combobox options={environments} />
// options have an icon field
<Combobox options={resources} />

Default, grouped, and with icons all use one component. Add group or icon to the options.

States

Default. Resting trigger, nothing selected.

Selected. The trigger shows the chosen label.

Disabled. Dimmed; the list cannot open.

Open. The list drops with the search input focused.

Searching. Typing narrows the list to matches.

Empty. No option matches the query.

Open, searching, and empty are interaction states. The open, searching, and empty cells render the underlying Command list inline so each is visible at rest.

API

Prop
Type
Default
Description
options
{ value, label, icon?, group? }[]
required
The selectable options. Add icon for a leading glyph, group to bucket under a heading.
value
string
undefined
Selected value when the combobox is controlled.
onValueChange
(value: string) => void
undefined
Called with the new value when the selection changes.
placeholder
string
"Select an option..."
Trigger text shown when nothing is selected.
disabled
boolean
false
Disables the trigger and blocks opening the list.

Don't and Do

Don't

Don't reach for a Combobox when the option list is short and fixed. A handful of choices the reader can scan at a glance does not benefit from a search field, and the extra step to type slows them down. Use a Select instead.

Do
<Combobox
  options={timezones}
  placeholder="Select a timezone..."
  onValueChange={setZone}
/>

Use it once the list is long enough that filtering meaningfully reduces the work of finding the right option.

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

const regions = [
  { value: "us-east", label: "US East (Virginia)" },
  { value: "eu-west", label: "EU West (Ireland)" },
  // ...a long list worth filtering
];

export function RegionPicker() {
  return (
    <Combobox
      options={regions}
      placeholder="Select a region..."
      searchPlaceholder="Search regions..."
    />
  );
}