# Combobox

> Searchable select with API-backed search, loading, and clear.

Import from `@aspyn-io/kit`. Scaffold source: `npx shadcn@latest add https://design.aspyn.io/r/combobox.json`

## Install

```tsx
import {
  Combobox,
  ComboboxInput,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxList,
  ComboboxItem,
  ComboboxGroup,
  ComboboxLabel,
  ComboboxCollection,
  ComboboxSeparator,
  ComboboxChips,
  ComboboxChip,
  ComboboxChipsInput,
  ComboboxValue,
  ComboboxTrigger,
  useComboboxAnchor,
} from "@aspyn-io/kit";
```

### Single select

Pass items to the root; ComboboxList renders each as a ComboboxItem. Built-in filtering + empty state.

```tsx
<Combobox items={frameworks}>
  <ComboboxInput placeholder="Select a framework" />
  <ComboboxContent>
    <ComboboxEmpty>No items found.</ComboboxEmpty>
    <ComboboxList>
      {(item) => <ComboboxItem key={item} value={item}>{item}</ComboboxItem>}
    </ComboboxList>
  </ComboboxContent>
</Combobox>
```

### Clearable

showClear adds a × button once something is selected.

```tsx
<Combobox items={frameworks} defaultValue={frameworks[0]}>
  <ComboboxInput placeholder="Select a framework" showClear />
  {/* … */}
</Combobox>
```

### Multiple (chips)

Add `multiple`; render selected values as ComboboxChip inside ComboboxChips, anchored via useComboboxAnchor.

```tsx
const anchor = useComboboxAnchor();

<Combobox multiple items={frameworks} defaultValue={[frameworks[0]]}>
  <ComboboxChips ref={anchor}>
    <ComboboxValue>
      {(values) => (
        <>
          {values.map((v) => <ComboboxChip key={v}>{v}</ComboboxChip>)}
          <ComboboxChipsInput />
        </>
      )}
    </ComboboxValue>
  </ComboboxChips>
  <ComboboxContent anchor={anchor}>
    <ComboboxList>{(item) => <ComboboxItem key={item} value={item}>{item}</ComboboxItem>}</ComboboxList>
  </ComboboxContent>
</Combobox>
```

### Grouped + separators

Group data as { value, items }; ComboboxGroup + ComboboxLabel + ComboboxCollection, with ComboboxSeparator between groups.

```tsx
<ComboboxList>
  {(group, index) => (
    <ComboboxGroup key={group.value} items={group.items}>
      <ComboboxLabel>{group.value}</ComboboxLabel>
      <ComboboxCollection>
        {(item) => <ComboboxItem key={item} value={item}>{item}</ComboboxItem>}
      </ComboboxCollection>
      {index < groups.length - 1 && <ComboboxSeparator />}
    </ComboboxGroup>
  )}
</ComboboxList>
```

### Custom item content

Object items with a title + description. Set itemToStringValue so typing filters by the label.

```tsx
<Combobox items={countries} itemToStringValue={(c) => c.label}>
  <ComboboxInput placeholder="Search countries…" />
  <ComboboxContent>
    <ComboboxList>
      {(country) => (
        <ComboboxItem key={country.code} value={country}>
          <Item size="sm" className="p-0">
            <ItemContent>
              <ItemTitle>{country.label}</ItemTitle>
              <ItemDescription>{country.continent}</ItemDescription>
            </ItemContent>
          </Item>
        </ComboboxItem>
      )}
    </ComboboxList>
  </ComboboxContent>
</Combobox>
```

### Button trigger

Open from a Button (ComboboxTrigger render) with the selected value shown via ComboboxValue and the search moved inside the popup.

```tsx
<Combobox items={countries}>
  <ComboboxTrigger render={<Button variant="outline" className="w-64 justify-between" />}>
    <ComboboxValue>{(v) => v?.label ?? "Select a country"}</ComboboxValue>
  </ComboboxTrigger>
  <ComboboxContent>
    <ComboboxInput showTrigger={false} placeholder="Search" />
    <ComboboxList>{(c) => <ComboboxItem key={c.code} value={c}>{c.label}</ComboboxItem>}</ComboboxList>
  </ComboboxContent>
</Combobox>
```

### Disabled & invalid

disabled and aria-invalid sit on ComboboxInput.

```tsx
<ComboboxInput disabled />
<ComboboxInput aria-invalid="true" />
```

## Notes

- Inherited from shadcn/ui — the Base UI Combobox (@base-ui/react): built-in filtering, keyboard highlight, item indicators, clear, grouping, and multi-select chips.
- ComboboxList takes a render-function child `(item) => <ComboboxItem>`; grouped lists nest ComboboxCollection inside ComboboxGroup.
- For object items, pass itemToStringValue so typing filters by the display string; ComboboxItem value is the whole item.
- Controlled via value / onValueChange on the root (a single item for single-select, an array for multiple).