# Combobox · JGuang UI

> Autocomplete input with a list of suggestions.

- Page: https://jiguang132.com/systems/jguang-ui/docs/components/base/combobox
- Based on: shadcn/ui documentation (MIT) @ bc0705384b51252af26dcc65425b216bf5eb063c

> Example `combobox-demo`: interactive preview on https://jiguang132.com/systems/jguang-ui/docs/components/base/combobox


## Installation


  

**Command**


  

**Manual**


```text
Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.
```


### Install the following dependencies:


```bash
npm install @base-ui/react
```


### Copy and paste the following code into your project.


[View complete source: components/ui/combobox.tsx](/r/jguang-ui/base/combobox.json)


### Update the import paths to match your project setup.


## Usage

```tsx showLineNumbers
import {
  Combobox,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
} from "@/components/ui/combobox"
```

```tsx showLineNumbers
const frameworks = ["Next.js", "SvelteKit", "Nuxt.js", "Remix", "Astro"]

export function ExampleCombobox() {
  return (
    <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>
  )
}
```

## Composition

### Simple

A single-line input and a flat list (see [Basic](#basic)).

```text
Combobox
├── ComboboxInput
└── ComboboxContent
    ├── ComboboxEmpty
    └── ComboboxList
        ├── ComboboxItem
        └── ComboboxItem
```

### With chips

Multi-select with `multiple`, chips, and a chips input (see [Multiple](#multiple)).

```text
Combobox
├── ComboboxChips
│   ├── ComboboxValue
│   │   └── ComboboxChip
│   └── ComboboxChipsInput
└── ComboboxContent
    ├── ComboboxEmpty
    └── ComboboxList
        ├── ComboboxItem
        └── ComboboxItem
```

### With groups and collection

Nested items per group using `ComboboxCollection` inside each `ComboboxGroup`, with a separator between groups (see [Groups](#groups)).

```text
Combobox
├── ComboboxInput
└── ComboboxContent
    ├── ComboboxEmpty
    └── ComboboxList
        ├── ComboboxGroup
        │   ├── ComboboxLabel
        │   └── ComboboxCollection
        │       ├── ComboboxItem
        │       └── ComboboxItem
        ├── ComboboxSeparator
        └── ComboboxGroup
            ├── ComboboxLabel
            └── ComboboxCollection
                ├── ComboboxItem
                └── ComboboxItem
```

## Custom Items

Use `itemToStringValue` when your items are objects.

```tsx showLineNumbers
import * as React from "react"

import {
  Combobox,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
} from "@/components/ui/combobox"

type Framework = {
  label: string
  value: string
}

const frameworks: Framework[] = [
  { label: "Next.js", value: "next" },
  { label: "SvelteKit", value: "sveltekit" },
  { label: "Nuxt", value: "nuxt" },
]

export function ExampleComboboxCustomItems() {
  return (
    <Combobox
      items={frameworks}
      itemToStringValue={(framework) => framework.label}
    >
      <ComboboxInput placeholder="Select a framework" />
      <ComboboxContent>
        <ComboboxEmpty>No items found.</ComboboxEmpty>
        <ComboboxList>
          {(framework) => (
            <ComboboxItem key={framework.value} value={framework}>
              {framework.label}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  )
}
```

## Multiple Selection

Use `multiple` with chips for multi-select behavior.

```tsx showLineNumbers
import * as React from "react"

import {
  Combobox,
  ComboboxChip,
  ComboboxChips,
  ComboboxChipsInput,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
  ComboboxValue,
} from "@/components/ui/combobox"

const frameworks = ["Next.js", "SvelteKit", "Nuxt.js", "Remix", "Astro"]

export function ExampleComboboxMultiple() {
  const [value, setValue] = React.useState<string[]>([])

  return (
    <Combobox
      items={frameworks}
      multiple
      value={value}
      onValueChange={setValue}
    >
      <ComboboxChips>
        <ComboboxValue>
          {value.map((item) => (
            <ComboboxChip key={item}>{item}</ComboboxChip>
          ))}
        </ComboboxValue>
        <ComboboxChipsInput placeholder="Add framework" />
      </ComboboxChips>
      <ComboboxContent>
        <ComboboxEmpty>No items found.</ComboboxEmpty>
        <ComboboxList>
          {(item) => (
            <ComboboxItem key={item} value={item}>
              {item}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  )
}
```

## Basic

A simple combobox with a list of frameworks.


> Example `combobox-basic`: interactive preview on https://jiguang132.com/systems/jguang-ui/docs/components/base/combobox


## Multiple

A combobox with multiple selection using `multiple` and `ComboboxChips`.


> Example `combobox-multiple`: interactive preview on https://jiguang132.com/systems/jguang-ui/docs/components/base/combobox


## Clear Button

Use the `showClear` prop to show a clear button.


> Example `combobox-clear`: interactive preview on https://jiguang132.com/systems/jguang-ui/docs/components/base/combobox


## Groups

Use `ComboboxGroup` and `ComboboxSeparator` to group items.


> Example `combobox-groups`: interactive preview on https://jiguang132.com/systems/jguang-ui/docs/components/base/combobox


## Custom Items

You can render a custom component inside `ComboboxItem`.


> Example `combobox-custom`: interactive preview on https://jiguang132.com/systems/jguang-ui/docs/components/base/combobox


## Invalid

Use the `aria-invalid` prop to make the combobox invalid.


> Example `combobox-invalid`: interactive preview on https://jiguang132.com/systems/jguang-ui/docs/components/base/combobox


## Disabled

Use the `disabled` prop to disable the combobox.


> Example `combobox-disabled`: interactive preview on https://jiguang132.com/systems/jguang-ui/docs/components/base/combobox


## Auto Highlight

Use the `autoHighlight` prop to automatically highlight the first item on filter.


> Example `combobox-auto-highlight`: interactive preview on https://jiguang132.com/systems/jguang-ui/docs/components/base/combobox


## Popup

You can trigger the combobox from a button or any other component by using the `render` prop. Move the `ComboboxInput` inside the `ComboboxContent`.


> Example `combobox-popup`: interactive preview on https://jiguang132.com/systems/jguang-ui/docs/components/base/combobox


## Input Group

You can add an addon to the combobox by using the `InputGroupAddon` component inside the `ComboboxInput`.


> Example `combobox-input-group`: interactive preview on https://jiguang132.com/systems/jguang-ui/docs/components/base/combobox


## RTL

To enable RTL support in JGuang UI, see the [RTL configuration guide](/systems/jguang-ui/docs/rtl).


> Example `combobox-rtl`: interactive preview on https://jiguang132.com/systems/jguang-ui/docs/components/base/combobox


## API Reference

See the [Base UI](https://base-ui.com/react/components/combobox#api-reference) documentation for more information.

---

Index of all JGuang resources: https://jiguang132.com/llms.txt