# Combobox

> Searchable select for one or many values, fully keyboard driven.

Component · Free · https://lodeui.com/components/combobox

## When to use

- Searchable choice from many options: country, assignee, repository.
- Choosing several values (multiple).

## When not to use

- Under ~8 options: use a select.

## Installation

```bash
npx shadcn@latest add https://lodeui.com/r/combobox.json
```

npm dependencies: motion, lucide-react

## Usage

```tsx title="example.tsx"
import * as React from "react";
import { Combobox } from "@/components/ui/combobox";

const people = [
  { value: "ada", label: "Ada Lovelace", description: "Engineering" },
  { value: "grace", label: "Grace Hopper", description: "Platform" },
];

export function Assignees() {
  const [value, setValue] = React.useState<string[]>([]);
  return <Combobox multiple aria-label="Assignees" options={people} value={value} onValueChange={setValue} />;
}
```

## API reference

### Combobox

A trigger with a searchable listbox. Single mode returns string | null; multiple mode returns string[].

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| options | `{ value; label; description?; icon? }[]` | – | Choices; search matches label and description. |
| multiple | `boolean` | `false` | Switches value to string[]. |
| value / onValueChange | `string \| null  /  string[]` | – | Controlled value. Choosing the selected option again clears it in single mode. |
| placeholder / searchPlaceholder / emptyMessage | `string` | `"Select…" / "Search…" / "No matches"` | Text. |

## Keyboard interactions

| Keys | Action |
| --- | --- |
| ↑ / ↓ | Move the highlight |
| Enter | Choose |
| Esc | Close |

## Accessibility

- The search field is a combobox controlling a listbox with aria-activedescendant.
- Multiple mode sets aria-multiselectable.

## Motion

- The menu scales in; chosen chips animate in the trigger.

## Responsive behavior

- Fills its container width.

## Performance

- Filtering is a substring match; fine for a few thousand options.

## Notes for AI

- Use the multiple prop and string[] state together, or TypeScript will complain.

## Related

- [Select](https://lodeui.com/components/select) — A pill trigger with a springy menu, typeahead, and full keyboard support.
- [Tag input](https://lodeui.com/components/tag-input) — Type, paste or pick suggestions to add tags; validates each one.
- [Command palette](https://lodeui.com/components/command-palette) — Type to filter, arrow to move, Enter to run. Inline or as a ⌘K dialog.