> A component of a Premium AI Canvas design system. Index of every system, component and install setup: https://aicanvas.me/llms.txt

# Combobox (Andromeda Pro)

Finds one thing in a known set as you type, from a list that opens under the field.

- Design system: [Andromeda Pro](https://aicanvas.me/design-systems/andromeda-pro.md)
- License: Premium (proprietary)
- Install slug: `andromeda-pro-combobox`
- Page: https://aicanvas.me/design-systems/andromeda-pro/combobox

## Install

```bash
npx shadcn@latest add @aicanvas/andromeda-pro-combobox
```

Requires Premium. Without a Premium token the command writes a placeholder instead of the component.

Every Andromeda Pro component at once: `npx shadcn@latest add @aicanvas/andromeda-pro`.

Token setup: the Install section of https://aicanvas.me/llms.txt.

## Props

### ComboboxOption

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  | Stable key; also what the caller matches on in `onSelect`. |
| `label` | `string` |  | The row's title, and what the default filter searches. |
| `icon?` | `React.ComponentType` |  | Icon shown as the row's plain leading glyph, sized by the row's rung. |
| `meta?` | `React.ReactNode` |  | Trailing metadata, read not clicked (a value, a date): 10px on text.muted. |
| `keywords?` | `string[]` |  | Extra words the default filter matches besides the label. |

### Combobox

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `options` | `ComboboxOption[]` |  | Everything the field can find. The list shows the ones `filter` keeps for the typed query. |
| `onSelect` | `(option: ComboboxOption) => void` |  | Called with the picked option, by Enter on the cursor row or a click. |
| `value?` | `string` |  | Controlled query (the typed text). Pair with `onValueChange`. |
| `defaultValue?` | `string` | `''` | Initial query of an uncontrolled field. |
| `defaultOpen?` | `boolean` | `false` | Show the results list at mount, without taking focus, when the field starts with a query. From then on it closes and opens as usual. For a page that documents the list. |
| `onValueChange?` | `(query: string) => void` |  | Called on every keystroke, and with '' when a pick clears the field. |
| `filter?` | `(option: ComboboxOption, query: string) => boolean` |  | Which options match the trimmed query. Defaults to a case-insensitive "includes" over the label and the keywords. |
| `size?` | `'sm'\|'md'` | `'md'` | Rung of the field (28 or 32px tall), and of the result rows unless `listSize` says otherwise. |
| `listSize?` | `'sm'\|'md'` |  | Rung of the result rows: 12px title and 16px glyph, or 14px and 18px. Defaults to `size`. A compact field in a top bar keeps md rows, so the results stay readable under a small field. |
| `placeholder?` | `string` | `'Search anything'` | Text shown in the empty field. |
| `ariaLabel?` | `string` |  | Accessible name of the input. Defaults to the placeholder. |
| `shortcut?` | `string\|null` | `'⌘ K'` | The field's keycap. Pass null to hide it. The caller binds the key itself, to the forwarded ref. |
| `emptyText?` | `(query: string) => React.ReactNode` |  | The line shown when nothing matches, given the trimmed query. Defaults to Nothing matches “query”. |
| `clearOnSelect?` | `boolean` | `true` | Empty the field after a pick. Set false to leave the query in place. |
| `width?` | `string\|number` | `'100%'` | Width of the field, any CSS length. The list matches it. |
| `className?` | `string` |  | Class on the outer wrapper. |
| `style?` | `React.CSSProperties` |  | Inline styles merged onto the outer wrapper. |

## Remix prompt

The public part of this component's remix prompt. The rest of the build spec is part of Premium.

```markdown
Build **Combobox**: a search field whose results open in a list under it. The field keeps focus the whole time: the arrow keys walk the results, Enter picks one, and Escape, a click outside or Tab away close the list. React + TypeScript, one file, named export `Combobox` (also default-export it), plus the exported types `ComboboxOption` and `ComboboxProps`.

It is drawn to sit on a near-black ground, `oklch(0.135 0.002 286.2)`. Typeface: Manrope, falling back to the system sans.

It draws nothing of its own. It is three parts put together: a search field is the field, a popover with NO trigger is the panel (the input owns open and close), and each result is a list row rendered as an option. Build those first, or reuse the ones you have; the values each part needs are restated below.
```

## More Andromeda Pro components

- [Corner Markers](https://aicanvas.me/design-systems/andromeda-pro/corner-markers.md)
- [Date Range Picker](https://aicanvas.me/design-systems/andromeda-pro/date-range-picker.md)
- [Drawer](https://aicanvas.me/design-systems/andromeda-pro/drawer.md)
- [Empty State](https://aicanvas.me/design-systems/andromeda-pro/empty-state.md)
- [Footer](https://aicanvas.me/design-systems/andromeda-pro/footer.md)
