Combobox

A searchable select — a styled trigger that opens a Popover containing a cmdk command list. Type to filter, use the arrow keys to move, and press Enter (or click) to select. Selected rows show a Check. Supports single-select and multi-select, controlled or uncontrolled.

Import

import { Combobox } from "@roger-emerson/ploxum-primitives";

Usage

const zones = [
  { label: "Pit Lane", value: "pit-lane" },
  { label: "Grandstand North", value: "grandstand-north" },
  { label: "Paddock Club", value: "paddock-club" },
];
 
function ZonePicker() {
  const [zone, setZone] = useState("");
  return (
    <Combobox
      onValueChange={setZone}
      options={zones}
      placeholder="Select a zone…"
      searchPlaceholder="Search zones…"
      value={zone}
    />
  );
}

For multi-select, pass multiple with values / onValuesChange:

<Combobox
  multiple
  onValuesChange={setZones}
  options={zones}
  values={zones}
/>

Props

Prop	Type	Default	Description
`options`	`ComboboxOption[]`	—	The selectable rows. Each is `{ value, label, icon?, disabled? }`.
`value`	`string`	—	Selected value for single-select (controlled).
`onValueChange`	`(value: string) => void`	—	Fires on single-select; the popover closes after selecting.
`values`	`string[]`	—	Selected values for multi-select (controlled).
`onValuesChange`	`(values: string[]) => void`	—	Fires on multi-select toggle; the popover stays open.
`multiple`	`boolean`	`false`	Enables multi-select. The trigger shows comma-joined labels.
`placeholder`	`string`	`"Select…"`	Trigger text when nothing is selected.
`searchPlaceholder`	`string`	`"Search…"`	Placeholder for the filter input.
`emptyMessage`	`string`	`"No results."`	Shown when the filter matches no options.
`disabled`	`boolean`	`false`	Disables the trigger.
`className`	`string`	—	Merged onto the trigger.
`ref`	`Ref<HTMLButtonElement>`	—	Forwarded to the trigger button.

Design rules

The trigger mirrors Select — same border, elevated surface, amber focus ring, and trailing ChevronDown. Use it when the option list is long enough to need search; reach for Select otherwise.
Selected rows use the amber-tint highlight and text-amber hue, matching CommandPalette.Item. The active row also shows a Check.
Keyboard navigation, filtering, and looping come from cmdk — the component adds only the trigger, the selection model, and the surface styling.
Single-select closes on choose; multi-select toggles and keeps the popover open so several values can be picked in one pass.
Both modes are controlled-or-uncontrolled: omit value / values and the component tracks selection internally.
Options can be individually disabled, and the whole control can be disabled via the trigger.

Storybook

Open Combobox in Storybook ↗