# Combobox

An input combined with a filterable list of predefined items to select.

- Category: Forms
- Page: https://wunderui.com/components/combobox
- Tier: Free

## Install

```bash
npx wunderui-cli add combobox
```

## Import

```tsx
import { Combobox, ComboboxEmpty, ComboboxGroup, ComboboxGroupLabel, ComboboxInput, ComboboxInputGroup, ComboboxItem, ComboboxItemGroup, ComboboxList, ComboboxPopup, ComboboxPortal, ComboboxProps, ComboboxTrigger } from "@/components/ui/combobox"
```

## Minimal usage

Then use it:

```tsx
import { useState } from "react"
import {
  Combobox,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxInputGroup,
  ComboboxItem,
  ComboboxList,
  ComboboxPopup,
  ComboboxTrigger,
} from "@/components/ui/combobox"

const projects = ["Brand refresh", "Mobile app", "Onboarding revamp", "Pricing experiment", "Q4 roadmap"]

export function ProjectField() {
  const [project, setProject] = useState<string | null>(null)

  return (
    <Combobox items={projects} value={project} onValueChange={setProject}>
      <ComboboxInputGroup>
        <ComboboxInput aria-label="Project" placeholder="Search projects" />
        <ComboboxTrigger />
      </ComboboxInputGroup>
      <ComboboxPopup>
        <ComboboxEmpty>No projects match.</ComboboxEmpty>
        <ComboboxList>
          {(item) => (
            <ComboboxItem key={item} value={item}>
              {item}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxPopup>
    </Combobox>
  )
}
```

Expected result: You see a field with the placeholder Search projects and a chevron. A click opens five projects, typing re keeps two, and Enter on one fills the field with its name.

## Usage

```tsx
import {
  Combobox,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxInputGroup,
  ComboboxItem,
  ComboboxList,
  ComboboxPopup,
  ComboboxTrigger,
} from "@/components/ui/combobox"
import { Label } from "@/components/ui/label"

const projects = ["Brand refresh", "Mobile app", "Onboarding revamp", "Pricing experiment", "Q4 roadmap"]

export function Example() {
  return (
    <div className="flex flex-col gap-2">
      <Label htmlFor="project">Project</Label>
      <Combobox items={projects}>
        <ComboboxInputGroup>
          <ComboboxInput id="project" placeholder="Search projects" />
          <ComboboxTrigger />
        </ComboboxInputGroup>
        <ComboboxPopup>
          <ComboboxEmpty>No projects match.</ComboboxEmpty>
          <ComboboxList>
            {(project) => (
              <ComboboxItem key={project} value={project}>
                {project}
              </ComboboxItem>
            )}
          </ComboboxList>
        </ComboboxPopup>
      </Combobox>
    </div>
  )
}
```

## When to use

### Use Combobox for

- Choosing one entry from a long list people can search, such as a country, a project or a person
- Choosing several entries, such as the teams to filter a table by
- Any field whose value must be one of the entries

### Use something else

- [Select](https://wunderui.com/components/select) for a short list where typing is not needed
- [Autocomplete](https://wunderui.com/components/autocomplete) for free text that only gets suggestions
- [Radio Group](https://wunderui.com/components/radio-group) for two to four options that should all be visible

## Keyboard

The input is a native text field, so the browser handles focus, typing and the caret. Focus stays in the input while the list is open, and the chevron button is not in the tab order.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus into the field and out of it. Leaving closes the list. Text that was typed but not chosen is dropped, and the field shows the chosen entry again. |
| `A–Z` | Typing opens the list and keeps the entries that match. |
| `ArrowDown` or `ArrowUp` | Opens the list if it is closed, then moves the highlight to the next or previous entry. With an entry chosen the list opens with it highlighted. At the end of the list focus goes back to the text with nothing highlighted. |
| `Enter` | Chooses the highlighted entry: the field shows its label and the list closes. With `multiple` it toggles the entry and the list stays open. |
| `Escape` | Closes the list. Pressed again, it clears the choice. |

## Behavior

What the field does with its value, the typed text, the list and motion.

- **A value from the list:** The value is an entry of the items, or null while nothing is chosen. Typing alone never sets it, so the value changes only when an entry is chosen.
- **Opening:** The list opens on a click in the field, on typing, on the chevron and on Arrow Down. The chevron button opens and closes it.
- **Filtering:** An entry matches when it contains the typed text, ignoring case and accents. You can replace the rule or cap the list, and after a choice the list opens unfiltered.
- **Groups:** Pass groups as items with a label and entries, and render a group and group label for each. The filter works across groups, and a group with no match disappears with its label.
- **Single and multiple:** By default one entry is chosen and the list closes. With multiple the value is an array, the list stays open and every chosen entry shows a check, but the field does not list them.
- **Objects as items:** Items can be objects. Give each item the object as its value, the root a function for the field text, and an equality check when the objects are not the same references.
- **Position and size:** The list opens 4 px below the field, as wide as the field, and flips above when there is no room below. It scrolls when it is taller than the room left.
- **Invalid and disabled:** Marking the input invalid turns the border and focus ring red, so say why in a line under the field. Disabling the root dims the field to 40 % and it ignores pointer and keyboard.
- **Previews in these docs:** The list normally floats over the page, but the previews here draw it inside the card. Point at a card or focus it, and the field behaves like the real one.
- **Motion:** The list appears and disappears at once. Nothing else on the field moves, and the border and focus ring change colour quickly.
- **Reduced motion:** There is no movement to remove, so reduced motion changes nothing. The colour change is a short fade and stays.

## Anatomy

- `Combobox`: The root. It holds the chosen value, the typed text, the items and the filter, and the value is an item or null, or an array with multiple.
- `ComboboxInputGroup`: The bordered frame around the input and the chevron, 36 px high with an 8 px corner. It draws the border and focus ring, dims when disabled and turns red when the input is invalid.
- `ComboboxInput`: The text input: typing filters the list, arrow keys move through it, Enter chooses and Escape closes. Give it a visible label or an aria-label.
- `ComboboxTrigger`: The chevron button that opens and closes the whole list. It is named Show options and is not in the tab order, because the keyboard opens the list from the input.
- `ComboboxPopup`: The list panel. It brings its own portal and positioner, matches the width of the field and scrolls when it runs out of room.
- `ComboboxList`: Renders the entries. Pass a render function as the child, so the filtered list, not the full one, is mapped, and with groups it receives one group at a time.
- `ComboboxGroup`: Holds the entries of one group under a group label. A group without a match disappears with its label.
- `ComboboxGroupLabel`: The heading of a group, in 12 px medium muted text. It is not an entry, so arrow keys skip it.
- `ComboboxItem`: One entry, 32 px high for a single line, whose value is what the field holds when chosen. A row can hold an icon, or an avatar and a second line, and the highlighted row takes the page fill.
- `Check`: A 16 px check at the right of the chosen entry. With multiple, every chosen entry shows one.
- `ComboboxEmpty`: A centred line shown in place of the list when nothing matches. It is hidden while it has no content.
- `ComboboxPortal`: Moves the list to the end of the document. The popup already renders it, so you only need it for a custom container.

## Best practices

### Do

- Give the input a visible label that points at it. The placeholder is a hint such as Search projects, not the name of the field.
- Always include an empty-state line with a sentence such as No projects match, so a list without matches never looks broken.
- Keep the state as a value or null. It is null while nothing is chosen and after the choice is cleared.
- With multiple, show the chosen entries next to the field, as a count or a list. The field only shows what people type.
- Group a long list by what people already know, such as an area or a team, and pass the groups as the items.

### Don't

- Don't use it for free text. Text that is not an entry is dropped when the field loses focus, so use an Autocomplete when any value is valid.
- Don't use it for a short list people can see at a glance. A Select is quicker when there are about a dozen options or fewer.
- Don't turn on multiple and then hide the choices. People cannot tell what is selected from a closed field with a placeholder.

## API reference

### Combobox

| Prop | Type | Default | Description |
|---|---|---|---|
| actionsRef | React.RefObject<ComboboxRoot.Actions \| null> |  | A ref to imperative actions. - `unmount`: Manually unmounts the combobox. Call this after any externally controlled closing animation finishes. |
| autoComplete | string |  | Provides a hint to the browser for autofill. |
| autoHighlight | boolean | false | Highlights the first matching entry while people type, so Enter chooses it. |
| children | React.ReactNode |  |  |
| defaultInputValue | React.ComponentProps<'input'>['defaultValue'] |  | The text the field starts with when you do not control it. |
| defaultOpen | boolean | false | Whether the list starts open when you do not control it. |
| defaultValue | ComboboxValueType<Value, Multiple> \| null |  | The entry that is chosen when you do not control the value. |
| disabled | boolean | false | Disables the field: it dims to 40 % and ignores the pointer and the keyboard. |
| filter | null \| ((item: Item, query: string, itemToString?: (item: Item) => string) => boolean) |  | Replaces the matching rule. It receives an entry, the typed text and the function that turns an entry into text, and returns whether the entry stays in the list. `null` switches filtering off. |
| filteredItems | readonly Item[] \| readonly Group<Item>[] |  | Filtered items to display in the list. When provided, the list uses these items instead of filtering the `items` prop internally. When `items` is also provided, this array must preserve its flat or grouped structure. With a `createItems()`… |
| form | string |  | Identifies the form that owns the internal input. Useful when the combobox is rendered outside the form. |
| grid | boolean | false | Whether list items are presented in a grid layout. When enabled, arrow keys navigate across rows and columns inferred from DOM rows. |
| highlightItemOnHover | boolean | true | Whether moving the pointer over items should highlight them. Disabling this prop allows CSS `:hover` to be differentiated from the `:focus` (`data-highlighted`) state. |
| id | string |  | The id of the component. |
| inline | boolean | false | Whether the list is rendered inline without using the component's own popup. Specify `open` unconditionally in conjunction with this prop so the list is considered visible: `<Combobox.Root inline open>` In a `Combobox.Root` > `Dialog.Root`… |
| inputRef | React.Ref<HTMLInputElement> |  | A ref to the hidden input element. |
| inputValue | React.ComponentProps<'input'>['value'] |  | The text in the field, when you control it. Pair it with `onInputValueChange`. |
| isItemEqualToValue | ((itemValue: Value, value: Value) => boolean) |  | Decides whether an entry is the chosen value. Needed when entries are objects that are not the same references as the value. |
| items | readonly Value[] \| readonly ComboboxItemGroup<Value>[] \| ComboboxItemCollection<Item, Value> |  | The entries: a flat array, an array of groups (`{ label, items }`) or a collection from `Combobox.createItems()`. A flat array or groups give `Value` its type. |
| itemToStringLabel | ((itemValue: Value) => string) |  | Turns an object entry into the text of the field and the text the filter matches against. Needed when the entries are objects. |
| itemToStringValue | ((itemValue: Value) => string) |  | When the item values are objects (`<Combobox.Item value={object}>`), this function converts the object value to a string representation for form submission. If the shape of the object is `{ value, label }`, the value will be used automatic… |
| limit | number | -1 | The most entries the list shows. `-1`, the default, shows every match. |
| locale | Intl.LocalesArgument |  | The locale to use for string comparison. Defaults to the user's runtime locale. |
| loopFocus | boolean | true | Whether to loop keyboard focus back to the input when the end of the list is reached while using the arrow keys. The first item can then be reached by pressing <kbd>ArrowDown</kbd> again from the input, or the last item can be reached by p… |
| modal | boolean | false | Determines if the popup enters a modal state when open. - `true`: user interaction is limited to the popup: document page scroll is locked and pointer interactions on outside elements are disabled. - `false`: user interaction with the rest… |
| multiple | Multiple | false | Lets people choose several entries. The value becomes an array, the list stays open while they choose, and each chosen entry shows a check. |
| name | string |  | The name the chosen value is submitted under in a form. |
| onInputValueChange | ((inputValue: string, eventDetails: ComboboxRoot.ChangeEventDetails) => void) |  | Called with the new text each time the person types or the field changes to show a choice. |
| onItemHighlighted | ((highlightedValue: Value \| undefined, eventDetails: ComboboxRoot.HighlightEventDetails) => void) |  | Callback fired when an item is highlighted or unhighlighted. Receives the highlighted item value (or `undefined` if no item is highlighted) and event details with a `reason` property describing why the highlight changed. The `reason` can b… |
| onOpenChange | ((open: boolean, eventDetails: ComboboxRoot.ChangeEventDetails) => void) |  | Called when the list opens or closes, with the reason, such as typing, a key press, an outside press or choosing an entry. |
| onOpenChangeComplete | ((open: boolean) => void) |  | Event handler called after any animations complete when the popup is opened or closed. |
| onValueChange | \| (( value: Multiple extends true ? Value[] : Value \| null, eventDetails: ComboboxPrimitive.Root.ChangeEventDetails ) => void) |  | Called with the new choice: the entry, or `null` when the choice is cleared. With `multiple` it is the whole array. |
| open | boolean |  | Whether the list is open, when you control it. Pair it with `onOpenChange`. |
| openOnInputClick | boolean | true | Opens the list when the field is clicked. On by default. |
| readOnly | boolean | false | Keeps the value but stops people from choosing another entry. |
| required | boolean | false | Marks the field as required for the form it belongs to. |
| value | ComboboxValueType<Value, Multiple> \| null |  | The chosen entry, or `null` while nothing is chosen. With `multiple` it is an array. It is a controlled value: update it in `onValueChange`. |
| virtualized | boolean | false | Whether the items are being externally virtualized. |

### ComboboxEmpty

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | Extra classes for the line shown when nothing matches. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |

Also accepts React.HTMLAttributes attributes.

### ComboboxGroup

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | Extra classes for the group wrapper. |
| items | readonly any[] |  | The entries of this group. Pass the group's own `items` so the list can tell which entries belong to it. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |

Also accepts React.HTMLAttributes attributes.

### ComboboxGroupLabel

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | Extra classes for the group heading. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |

Also accepts React.HTMLAttributes attributes.

### ComboboxInput

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | Extra classes for the input inside the frame. |
| disabled | boolean | false | Disables this input only. Prefer `disabled` on the root, which also dims the frame. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |

Also accepts React.InputHTMLAttributes attributes.

### ComboboxInputGroup

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | Extra classes for the frame, for example `w-72` for a fixed width or `h-(--field-lg)` for the large height. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |

Also accepts React.HTMLAttributes attributes.

### ComboboxItem

| Prop | Type | Default | Description |
|---|---|---|---|
| children | React.ReactNode |  |  |
| className | string \| ((state: State) => string \| undefined) |  | Extra classes for the row, for example `gap-3` for a row with an avatar. |
| disabled | boolean | false | Stops the row from being highlighted or chosen. |
| index | number |  | The index of the item in the list. Improves performance when specified by avoiding the need to calculate the index automatically from the DOM. |
| nativeButton | boolean | false | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `true` if the rendered element is a native button. |
| onClick | BaseUIComponentProps<'div', ComboboxItemState>['onClick'] |  | Called when the row is clicked or chosen with Enter. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |
| value | any | null | The entry this row stands for, the same string or object as in `items`. It is what the field holds when the row is chosen. |

Also accepts React.HTMLAttributes attributes.

### ComboboxList

| Prop | Type | Default | Description |
|---|---|---|---|
| children | React.ReactNode \| ((item: any, index: number) => React.ReactNode) |  | A render function that receives the entries that match, or the groups that have a match, and returns the rows. |
| className | string \| ((state: State) => string \| undefined) |  | Extra classes for the list element inside the panel. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |

Also accepts React.HTMLAttributes attributes.

### ComboboxPopup

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | Extra classes for the list panel, for example `min-w-64` to make it wider than the field. |
| finalFocus | boolean \| React.RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => void \| boolean \| HTMLElement \| null) |  | Where focus goes when the list closes. It stays in the input by default. |
| initialFocus | boolean \| React.RefObject<HTMLElement \| null> \| ((openType: InteractionType) => void \| boolean \| HTMLElement \| null) |  | Where focus goes when the list opens. It stays in the input by default, so people can keep typing. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |

Also accepts React.HTMLAttributes attributes.

### ComboboxPortal

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | CSS class applied to the element, or a function that returns a class based on the component's state. |
| container | HTMLElement \| ShadowRoot \| React.RefObject<HTMLElement \| ShadowRoot \| null> \| null |  | The element the list is moved into. The end of the document by default. |
| keepMounted | boolean | false | Keeps the list in the DOM while it is closed. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |

Also accepts React.HTMLAttributes attributes.

### ComboboxTrigger

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | Extra classes for the chevron button. |
| disabled | boolean | false | Disables the chevron button only. |
| nativeButton | boolean | true | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`). |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |

Also accepts React.ButtonHTMLAttributes attributes.

## Examples

### Content: text, groups or a person

```tsx
import {
  Combobox,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxInputGroup,
  ComboboxItem,
  ComboboxList,
  ComboboxPopup,
  ComboboxTrigger,
} from "@/components/ui/combobox"
import { Label } from "@/components/ui/label"

const projects = ["Brand refresh", "Mobile app", "Onboarding revamp", "Pricing experiment", "Q4 roadmap"]

export function Example() {
  return (
    <div className="flex flex-col gap-2">
      <Label htmlFor="project">Project</Label>
      <Combobox items={projects}>
        <ComboboxInputGroup>
          <ComboboxInput id="project" placeholder="Search projects" />
          <ComboboxTrigger />
        </ComboboxInputGroup>
        <ComboboxPopup>
          <ComboboxEmpty>No projects match.</ComboboxEmpty>
          <ComboboxList>
            {(project) => (
              <ComboboxItem key={project} value={project}>
                {project}
              </ComboboxItem>
            )}
          </ComboboxList>
        </ComboboxPopup>
      </Combobox>
    </div>
  )
}
```

### Selection: one choice or several

```tsx
import { useState } from "react"
import {
  Combobox,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxInputGroup,
  ComboboxItem,
  ComboboxList,
  ComboboxPopup,
  ComboboxTrigger,
} from "@/components/ui/combobox"
import { Label } from "@/components/ui/label"

const projects = ["Brand refresh", "Mobile app", "Onboarding revamp", "Pricing experiment", "Q4 roadmap"]

export function Example() {
  const [project, setProject] = useState<string | null>(null)

  return (
    <div className="flex flex-col gap-2">
      <Label htmlFor="project">Project</Label>
      <Combobox
        items={projects}
        value={project}
        onValueChange={setProject}
      >
        <ComboboxInputGroup>
          <ComboboxInput id="project" placeholder="Search projects" />
          <ComboboxTrigger />
        </ComboboxInputGroup>
        <ComboboxPopup>
          <ComboboxEmpty>No projects match.</ComboboxEmpty>
          <ComboboxList>
            {(project) => (
              <ComboboxItem key={project} value={project}>
                {project}
              </ComboboxItem>
            )}
          </ComboboxList>
        </ComboboxPopup>
      </Combobox>
    </div>
  )
}
```

### Field: with a chevron or input only

```tsx
import {
  Combobox,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxInputGroup,
  ComboboxItem,
  ComboboxList,
  ComboboxPopup,
  ComboboxTrigger,
} from "@/components/ui/combobox"
import { Label } from "@/components/ui/label"

const projects = ["Brand refresh", "Mobile app", "Onboarding revamp", "Pricing experiment", "Q4 roadmap"]

export function Example() {
  return (
    <div className="flex flex-col gap-2">
      <Label htmlFor="project">Project</Label>
      <Combobox items={projects}>
        <ComboboxInputGroup>
          <ComboboxInput id="project" placeholder="Search projects" />
          <ComboboxTrigger />
        </ComboboxInputGroup>
        <ComboboxPopup>
          <ComboboxEmpty>No projects match.</ComboboxEmpty>
          <ComboboxList>
            {(project) => (
              <ComboboxItem key={project} value={project}>
                {project}
              </ComboboxItem>
            )}
          </ComboboxList>
        </ComboboxPopup>
      </Combobox>
    </div>
  )
}
```

### States: default, filled, invalid and disabled

```tsx
import {
  Combobox,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxInputGroup,
  ComboboxItem,
  ComboboxList,
  ComboboxPopup,
  ComboboxTrigger,
} from "@/components/ui/combobox"
import { Label } from "@/components/ui/label"

const projects = ["Brand refresh", "Mobile app", "Onboarding revamp", "Pricing experiment", "Q4 roadmap"]

export function Example() {
  return (
    <div className="flex flex-col gap-2">
      <Label htmlFor="project">Project</Label>
      <Combobox items={projects}>
        <ComboboxInputGroup>
          <ComboboxInput id="project" placeholder="Search projects" />
          <ComboboxTrigger />
        </ComboboxInputGroup>
        <ComboboxPopup>
          <ComboboxEmpty>No projects match.</ComboboxEmpty>
          <ComboboxList>
            {(project) => (
              <ComboboxItem key={project} value={project}>
                {project}
              </ComboboxItem>
            )}
          </ComboboxList>
        </ComboboxPopup>
      </Combobox>
    </div>
  )
}
```

## In context

### Country in a shipping form

The field only ever holds a country from the list, so the line under it can promise a delivery time. Type Spa and press Enter.

```tsx
import { useState } from "react"
import {
  Combobox,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxInputGroup,
  ComboboxItem,
  ComboboxList,
  ComboboxPopup,
  ComboboxTrigger,
} from "@/components/ui/combobox"
import { Input } from "@/components/ui/input"
import { Label } from "@/components/ui/label"

const countries = ["Denmark", "Germany", "Portugal", "Spain", "United States"]

const delivery: Record<string, string> = {
  Denmark: "2 to 3 working days",
  Germany: "2 to 3 working days",
  Portugal: "3 to 5 working days",
  Spain: "4 to 6 working days",
  "United States": "7 to 10 working days",
}

export function ShippingCountry() {
  const [country, setCountry] = useState<string | null>("Portugal")

  return (
    <form className="flex flex-col gap-4">
      <div className="flex flex-col gap-2">
        <Label htmlFor="name">Full name</Label>
        <Input id="name" defaultValue="Maya Kessler" autoComplete="name" />
      </div>
      <div className="flex flex-col gap-2">
        <Label htmlFor="country">Country</Label>
        <Combobox items={countries} value={country} onValueChange={setCountry}>
          <ComboboxInputGroup>
            <ComboboxInput id="country" placeholder="Search countries" autoComplete="country-name" />
            <ComboboxTrigger />
          </ComboboxInputGroup>
          <ComboboxPopup>
            <ComboboxEmpty>No country matches.</ComboboxEmpty>
            <ComboboxList>
              {(item) => (
                <ComboboxItem key={item} value={item}>
                  {item}
                </ComboboxItem>
              )}
            </ComboboxList>
          </ComboboxPopup>
        </Combobox>
        <p className="text-xs text-text-tertiary">
          {country ? `Delivery in ${delivery[country]}.` : "Choose a country to see the delivery time."}
        </p>
      </div>
    </form>
  )
}
```

### Filter members by team

A multiple Combobox as a filter: the table follows the choice, and no team chosen shows everyone. The list stays open while you choose.

```tsx
import { useState } from "react"
import {
  Combobox,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxInputGroup,
  ComboboxItem,
  ComboboxList,
  ComboboxPopup,
  ComboboxTrigger,
} from "@/components/ui/combobox"
import { Label } from "@/components/ui/label"

const teams = ["Design", "Engineering", "Product", "Support"]

const members = [
  { name: "Nora Lindgren", team: "Design" },
  { name: "Daniel Okafor", team: "Engineering" },
  { name: "Priya Raman", team: "Product" },
  { name: "Tomás Ferreira", team: "Support" },
  { name: "Maya Kessler", team: "Engineering" },
]

export function FilterByTeam() {
  const [selected, setSelected] = useState<string[]>(["Engineering"])
  const rows = selected.length === 0 ? members : members.filter((member) => selected.includes(member.team))

  return (
    <div className="flex flex-col gap-4">
      <div className="flex flex-col gap-2">
        <div className="flex items-center justify-between">
          <Label htmlFor="team">Team</Label>
          <span className="text-xs text-text-tertiary">{selected.length} selected</span>
        </div>
        <Combobox multiple items={teams} value={selected} onValueChange={setSelected}>
          <ComboboxInputGroup>
            <ComboboxInput id="team" placeholder="Search teams" />
            <ComboboxTrigger />
          </ComboboxInputGroup>
          <ComboboxPopup>
            <ComboboxEmpty>No team matches.</ComboboxEmpty>
            <ComboboxList>
              {(team) => (
                <ComboboxItem key={team} value={team}>
                  {team}
                </ComboboxItem>
              )}
            </ComboboxList>
          </ComboboxPopup>
        </Combobox>
      </div>
      <ul className="divide-y divide-border overflow-hidden rounded-xl border border-border bg-card">
        {rows.map((member) => (
          <li key={member.name} className="flex h-11 items-center justify-between px-4 text-sm">
            <span className="font-medium text-foreground">{member.name}</span>
            <span className="text-text-secondary">{member.team}</span>
          </li>
        ))}
      </ul>
    </div>
  )
}
```

### Move a task to a project

Projects are grouped by area, and the filter works across groups. A group with no match disappears with its label.

```tsx
import { useState } from "react"
import {
  Combobox,
  ComboboxEmpty,
  ComboboxGroup,
  ComboboxGroupLabel,
  ComboboxInput,
  ComboboxInputGroup,
  ComboboxItem,
  ComboboxList,
  ComboboxPopup,
  ComboboxTrigger,
} from "@/components/ui/combobox"
import { Label } from "@/components/ui/label"

const projects = [
  { label: "Design", items: ["Brand refresh", "Design system"] },
  { label: "Product", items: ["Mobile app", "Q4 roadmap"] },
]

export function MoveTask() {
  const [project, setProject] = useState<string | null>("Q4 roadmap")

  return (
    <div className="flex flex-col gap-4">
      <div className="rounded-xl border border-border bg-card p-4">
        <p className="text-sm font-medium text-foreground">Update the pricing page</p>
        <p className="text-xs text-text-tertiary">In {project ?? "no project"}</p>
      </div>
      <div className="flex flex-col gap-2">
        <Label htmlFor="project">Move to</Label>
        <Combobox<string> items={projects} value={project} onValueChange={setProject}>
          <ComboboxInputGroup>
            <ComboboxInput id="project" placeholder="Search projects" />
            <ComboboxTrigger />
          </ComboboxInputGroup>
          <ComboboxPopup>
            <ComboboxEmpty>No projects match.</ComboboxEmpty>
            <ComboboxList>
              {(group) => (
                <ComboboxGroup key={group.label} items={group.items}>
                  <ComboboxGroupLabel>{group.label}</ComboboxGroupLabel>
                  {group.items.map((project) => (
                    <ComboboxItem key={project} value={project}>
                      {project}
                    </ComboboxItem>
                  ))}
                </ComboboxGroup>
              )}
            </ComboboxList>
          </ComboboxPopup>
        </Combobox>
      </div>
    </div>
  )
}
```

## For AI agents

`get_component("combobox")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
