# Combobox

> A value picked from a long list you can search: a time zone, a category, a set of tags. Options come as data, in groups, with keywords that find them. It takes one value or several, can create what was typed, and marks an option picked for the person, such as by a model, so they confirm or change it. On the overlay surface, with the command palette's rows.

Section: Forms. Docs: https://entrepta.vercel.app/docs/components/combobox

## Install

```bash
npx @entrepta/cli@latest add combobox
```

Files: `primitives/combobox.tsx`, `hooks/use-command-palette.ts`, `primitives/kbd.tsx`, `lib/overlay.ts`, `feedback/command-palette.tsx`, `primitives/popover.tsx`, `lib/icon.tsx`, `primitives/badge.tsx`, `primitives/input.tsx`.
npm packages: `cmdk`, `@radix-ui/react-dialog`, `@phosphor-icons/react`, `@radix-ui/react-popover`, `class-variance-authority`.
Comes with: `use-command-palette`, `kbd`, `overlay-lib`, `command-palette`, `popover`, `icon-lib`, `badge`, `input`.

## Usage

```tsx
import { Combobox } from "@/components/entrepta/combobox"

<Field id="zone" label="time zone">
  <Combobox
    options={[
      { value: "America/Sao_Paulo", label: "São Paulo", group: "Americas", keywords: ["brazil"] },
      { value: "Europe/Lisbon", label: "Lisbon", group: "Europe", hint: "UTC+1" },
    ]}
    value={zone}
    onValueChange={setZone}
    searchPlaceholder="Search time zones…"
    emptyText="No time zones match"
  />
</Field>

// several values, created on the spot
<Combobox
  aria-label="tags"
  multiple
  creatable
  onCreate={(label) => addTag(label)}   // returns the new value
  options={tags}
  value={chosen}
  onValueChange={setChosen}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `options` | `{ value; label; group?; hint?; keywords?; suggested?; disabled? }[]` | - | The list. group is the heading an option sits under |
| `value / onValueChange` | `string \| null, or string[] with multiple` | - | Controlled. With multiple, each pick toggles and the list stays open |
| `multiple` | `boolean` | false | Several values, shown as two chips and a count |
| `creatable / onCreate` | `boolean / (label: string) => string` | - | Offer to create what was typed when nothing matches it; the returned value is selected |
| `renderOption` | `(option) => ReactNode` | - | The row's content, such as an IconTile and a name |
| `emptyText, searchPlaceholder, createLabel, suggestedLabel` | `ReactNode, string, (query) => ReactNode, string` | - | The words, for another language or a more precise message |