Combobox — Rocket Design Spec

Overview

Combobox is a searchable dropdown for choosing one value from a filtered list. The trigger is an input field that filters options as the user types. Reuses the same visual tokens as Input/Select (bg, border, focus ring, sizing).

Wraps shadcn Combobox (@base-ui/react Combobox primitive).

v1 scope: Single-select only. Multi-select (chips) deferred to v2.

Sub-components

Re-exported from shadcn (no token overrides)

ComboboxValue, ComboboxGroup, ComboboxCollection

Props (ComboboxInput)

Sizes (trigger/input)

Token Mapping — Input/Trigger

Token Mapping — Content (dropdown)

Token Mapping — Item

Token Mapping — Empty

Slots

• search icon (leading, optional, ReactNode) — defaults to Search from lucide
• clear button (trailing, optional) — controlled via showClear prop
• chevron trigger (trailing, optional) — controlled via showTrigger prop
• leading icon on items (optional, ReactNode) — via children composition

States

CVA Shape

Shape C — sizes only (no variant axis). States handled via CSS pseudo-classes and aria attributes.

Composition

Basic

<Combobox>
  <ComboboxInput placeholder="Search..." />
  <ComboboxContent>
    <ComboboxList>
      <ComboboxItem value="react">React</ComboboxItem>
      <ComboboxItem value="vue">Vue</ComboboxItem>
      <ComboboxItem value="svelte">Svelte</ComboboxItem>
    </ComboboxList>
    <ComboboxEmpty>No results found.</ComboboxEmpty>
  </ComboboxContent>
</Combobox>

With Field

<Field>
  <FieldLabel>Framework</FieldLabel>
  <Combobox>
    <ComboboxInput placeholder="Search frameworks..." />
    <ComboboxContent>
      <ComboboxList>
        <ComboboxItem value="react">React</ComboboxItem>
        <ComboboxItem value="vue">Vue</ComboboxItem>
      </ComboboxList>
      <ComboboxEmpty>No results found.</ComboboxEmpty>
    </ComboboxContent>
  </Combobox>
</Field>

With clear and groups

<Combobox>
  <ComboboxInput placeholder="Select country..." showClear />
  <ComboboxContent>
    <ComboboxList>
      <ComboboxGroup>
        <ComboboxLabel>Americas</ComboboxLabel>
        <ComboboxItem value="us">United States</ComboboxItem>
        <ComboboxItem value="ca">Canada</ComboboxItem>
      </ComboboxGroup>
      <ComboboxSeparator />
      <ComboboxGroup>
        <ComboboxLabel>Europe</ComboboxLabel>
        <ComboboxItem value="uk">United Kingdom</ComboboxItem>
        <ComboboxItem value="de">Germany</ComboboxItem>
      </ComboboxGroup>
    </ComboboxList>
    <ComboboxEmpty>No countries found.</ComboboxEmpty>
  </ComboboxContent>
</Combobox>

Notes

• Trigger chevron: ChevronDown (lucide) — same as Select.
• Search icon: Search (lucide) — shown as leading icon inside input.
• Clear button: X (lucide) — shown when showClear is true and a value is selected.
• Loading state replaces the chevron trigger with a Spinner component.
• readOnly allows opening the dropdown to see options but prevents typing to filter.
• Multi-select (chips) support deferred to v2 — shadcn primitive supports it via ComboboxChips.
• Empty state shown when filter query matches no items.

Truncating long values (opt-in pattern)

Combobox itself does not auto-truncate. To reveal long content on hover, opt in by composing with TruncatingText. It uses the browser's native title attribute, so no provider or extra wiring is needed.

Option rows (in the dropdown)

ComboboxItem children render as the row label. Wrap them in TruncatingText per row — string children make auto-detection work:

<Combobox items={queries}>
  <ComboboxInput placeholder="Search query..." />
  <ComboboxContent>
    <ComboboxList>
      {(item) => (
        <ComboboxItem key={item.value} value={item}>
          <TruncatingText>{item.name}</TruncatingText>
        </ComboboxItem>
      )}
    </ComboboxList>
    <ComboboxEmpty>No results found.</ComboboxEmpty>
  </ComboboxContent>
</Combobox>

Selected value (in the input) — built in

The Combobox input trigger handles overflow itself, no opt-in required:

• Visual ellipsis — comboboxInputVariants carries [&_input]:tw-truncate, so blurred input values that overflow show … at the right edge. Focused inputs scroll horizontally per browser default.
• Native hover tooltip — ComboboxInput calls the useInputOverflowTitle hook, which detects overflow on the inner input and sets input.title = input.value when overflowing (removing it when the value fits). On blur, input.scrollLeft is reset to 0 so the ellipsis reappears reliably.

Limitation: programmatic writes to input.value (Base UI updating the value after a dropdown pick) do not fire input events per HTML spec. The title attribute may be momentarily stale after a selection change until the next user interaction (typing, blur, resize). Visually the ellipsis is always correct.

Why opt-in, not built-in

Same reasoning as Select. Truncation is a layout decision per callsite. Forcing it into the primitive would require modifying the primitive itself and would couple every consumer to that decision.