Combobox

Import

import {
  Combobox,
  ComboboxInput,
  ComboboxContent,
  ComboboxList,
  ComboboxItem,
  ComboboxGroup,
  ComboboxLabel,
  ComboboxCollection,
  ComboboxEmpty,
  ComboboxSeparator,
  ComboboxChips,
  ComboboxChip,
  ComboboxChipsInput,
  ComboboxTrigger,
  ComboboxValue,
  useComboboxAnchor,
} from "@timelycare/helix-ui"

Props

// Combobox — Root wrapper (re-exports ComboboxPrimitive.Root from @base-ui/react)
interface ComboboxProps extends ComboboxPrimitive.Root.Props {
  value?: string | string[]
  defaultValue?: string | string[]
  onValueChange?: (value: string | string[]) => void
  open?: boolean
  onOpenChange?: (open: boolean) => void
  disabled?: boolean
  multiple?: boolean
}

// ComboboxInput — Search input with optional trigger/clear buttons
interface ComboboxInputProps extends ComboboxPrimitive.Input.Props {
  showTrigger?: boolean   // default: true — renders chevron trigger button
  showClear?: boolean     // default: false — renders X clear button
  disabled?: boolean      // default: false
}

// ComboboxContent — Popup container with positioning
interface ComboboxContentProps extends ComboboxPrimitive.Popup.Props {
  side?: "top" | "bottom" | "left" | "right"   // default: "bottom"
  sideOffset?: number                            // default: 6
  align?: "start" | "center" | "end"            // default: "start"
  alignOffset?: number                           // default: 0
  anchor?: React.RefObject<HTMLElement | null> | HTMLElement | null
}

// ComboboxItem — Individual option
interface ComboboxItemProps extends ComboboxPrimitive.Item.Props {
  value: string
  disabled?: boolean
  className?: string
  children: React.ReactNode
}

// ComboboxChip — Tag/badge for multi-select
interface ComboboxChipProps extends ComboboxPrimitive.Chip.Props {
  showRemove?: boolean   // default: true — renders X remove button
}

// ComboboxChipsInput — Inline input inside the chips container
interface ComboboxChipsInputProps extends ComboboxPrimitive.Input.Props {}

// ComboboxGroup, ComboboxLabel, ComboboxList, ComboboxCollection,
// ComboboxEmpty, ComboboxSeparator, ComboboxTrigger, ComboboxValue
// all pass through their respective ComboboxPrimitive.*.Props

// useComboboxAnchor — hook returning a ref for anchoring the popup to a custom element
function useComboboxAnchor(): React.RefObject<HTMLDivElement | null>

Structure

States

Input States

Item States

Content Animation

Chips States

Icons

Common Patterns

Basic Combobox

const frameworks = [
  { value: "react", label: "React" },
  { value: "vue", label: "Vue" },
  { value: "angular", label: "Angular" },
  { value: "svelte", label: "Svelte" },
]

<Combobox>
  <ComboboxInput placeholder="Select framework..." />
  <ComboboxContent>
    <ComboboxList>
      <ComboboxEmpty>No framework found.</ComboboxEmpty>
      {frameworks.map((framework) => (
        <ComboboxItem key={framework.value} value={framework.value}>
          {framework.label}
        </ComboboxItem>
      ))}
    </ComboboxList>
  </ComboboxContent>
</Combobox>

Combobox with Clear Button

<Combobox>
  <ComboboxInput
    placeholder="Select framework..."
    showTrigger={true}
    showClear={true}
  />
  <ComboboxContent>
    <ComboboxList>
      <ComboboxEmpty>No framework found.</ComboboxEmpty>
      {frameworks.map((framework) => (
        <ComboboxItem key={framework.value} value={framework.value}>
          {framework.label}
        </ComboboxItem>
      ))}
    </ComboboxList>
  </ComboboxContent>
</Combobox>

Multi-Select with Chips

function MultiSelectCombobox() {
  const anchor = useComboboxAnchor()

  return (
    <Combobox multiple>
      <ComboboxChips ref={anchor}>
        {(item) => (
          <ComboboxChip key={item.value} value={item.value}>
            {item.label}
          </ComboboxChip>
        )}
        <ComboboxChipsInput placeholder="Select items..." />
      </ComboboxChips>
      <ComboboxContent anchor={anchor}>
        <ComboboxList>
          <ComboboxEmpty>No results.</ComboboxEmpty>
          {items.map((item) => (
            <ComboboxItem key={item.value} value={item.value}>
              {item.label}
            </ComboboxItem>
          ))}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  )
}

Grouped Items

<Combobox>
  <ComboboxInput placeholder="Search..." />
  <ComboboxContent>
    <ComboboxList>
      <ComboboxEmpty>No results found.</ComboboxEmpty>
      <ComboboxGroup>
        <ComboboxLabel>Frameworks</ComboboxLabel>
        <ComboboxItem value="react">React</ComboboxItem>
        <ComboboxItem value="vue">Vue</ComboboxItem>
      </ComboboxGroup>
      <ComboboxSeparator />
      <ComboboxGroup>
        <ComboboxLabel>Build Tools</ComboboxLabel>
        <ComboboxItem value="vite">Vite</ComboboxItem>
        <ComboboxItem value="webpack">Webpack</ComboboxItem>
      </ComboboxGroup>
    </ComboboxList>
  </ComboboxContent>
</Combobox>

With Searchable Content in Popup

<Combobox>
  <ComboboxTrigger>
    <ComboboxValue placeholder="Select item..." />
  </ComboboxTrigger>
  <ComboboxContent>
    <ComboboxInput placeholder="Filter..." />
    <ComboboxList>
      <ComboboxEmpty>Nothing found.</ComboboxEmpty>
      {items.map((item) => (
        <ComboboxItem key={item.value} value={item.value}>
          {item.label}
        </ComboboxItem>
      ))}
    </ComboboxList>
  </ComboboxContent>
</Combobox>

Controlled Value

const [value, setValue] = useState("")

<Combobox value={value} onValueChange={setValue}>
  <ComboboxInput placeholder="Select framework..." />
  <ComboboxContent>
    <ComboboxList>
      <ComboboxEmpty>No framework found.</ComboboxEmpty>
      {frameworks.map((framework) => (
        <ComboboxItem key={framework.value} value={framework.value}>
          {framework.label}
        </ComboboxItem>
      ))}
    </ComboboxList>
  </ComboboxContent>
</Combobox>

Accessibility

• Built on @base-ui/react Combobox — implements WAI-ARIA combobox pattern natively
• Arrow Up/Down navigates highlighted items
• Enter selects the currently highlighted item
• Escape closes the popup
• Type-ahead filtering via the input
• aria-expanded, aria-activedescendant, and aria-selected managed automatically
• Supports pointer-coarse media query for larger touch targets (labels: text-sm, check icon: size-5)

Gotchas

See Also

• Related Components: Select (without search), Command (command palette), Form (form integration)
• Internal Dependencies: InputGroup (used by ComboboxInput), Button (used by clear/chip remove)
• Accessibility: Forms Accessibility — Combobox ARIA patterns
• Patterns: Component Match — Select vs Combobox

Last updated: February 24, 2026