snapshot of https://github.com/shadcn-ui/ui.git (main, 2026-09-15; blobs > 131072B omitted)
This commit is contained in:
upstream-mirror
326
apps/v4/content/docs/components/radix/combobox.mdx
Normal file
326
apps/v4/content/docs/components/radix/combobox.mdx
Normal file
@@ -0,0 +1,326 @@
|
||||
---
|
||||
title: Combobox
|
||||
description: Autocomplete input with a list of suggestions.
|
||||
base: radix
|
||||
component: true
|
||||
links:
|
||||
doc: https://base-ui.com/react/components/combobox
|
||||
api: https://base-ui.com/react/components/combobox#api-reference
|
||||
---
|
||||
|
||||
<ComponentPreview
|
||||
styleName="base-nova"
|
||||
name="combobox-demo"
|
||||
description="A combobox with a list of frameworks."
|
||||
/>
|
||||
|
||||
## Installation
|
||||
|
||||
<CodeTabs>
|
||||
|
||||
<TabsList>
|
||||
<TabsTrigger value="cli">Command</TabsTrigger>
|
||||
<TabsTrigger value="manual">Manual</TabsTrigger>
|
||||
</TabsList>
|
||||
<TabsContent value="cli">
|
||||
|
||||
```bash
|
||||
npx shadcn@latest add combobox
|
||||
```
|
||||
|
||||
</TabsContent>
|
||||
<TabsContent value="manual">
|
||||
|
||||
<Steps className="mb-0 pt-2">
|
||||
|
||||
<Step>Install the following dependencies:</Step>
|
||||
|
||||
```bash
|
||||
npm install @base-ui/react
|
||||
```
|
||||
|
||||
<Step>Copy and paste the following code into your project.</Step>
|
||||
|
||||
<ComponentSource
|
||||
name="combobox"
|
||||
title="components/ui/combobox.tsx"
|
||||
styleName="base-nova"
|
||||
/>
|
||||
|
||||
<Step>Update the import paths to match your project setup.</Step>
|
||||
|
||||
</Steps>
|
||||
|
||||
</TabsContent>
|
||||
|
||||
</CodeTabs>
|
||||
|
||||
## 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.
|
||||
|
||||
<ComponentPreview styleName="base-nova" name="combobox-basic" />
|
||||
|
||||
## Multiple
|
||||
|
||||
A combobox with multiple selection using `multiple` and `ComboboxChips`.
|
||||
|
||||
<ComponentPreview styleName="base-nova" name="combobox-multiple" />
|
||||
|
||||
## Clear Button
|
||||
|
||||
Use the `showClear` prop to show a clear button.
|
||||
|
||||
<ComponentPreview styleName="base-nova" name="combobox-clear" />
|
||||
|
||||
## Groups
|
||||
|
||||
Use `ComboboxGroup` and `ComboboxSeparator` to group items.
|
||||
|
||||
<ComponentPreview styleName="base-nova" name="combobox-groups" />
|
||||
|
||||
## Custom Items
|
||||
|
||||
You can render a custom component inside `ComboboxItem`.
|
||||
|
||||
<ComponentPreview styleName="base-nova" name="combobox-custom" />
|
||||
|
||||
## Invalid
|
||||
|
||||
Use the `aria-invalid` prop to make the combobox invalid.
|
||||
|
||||
<ComponentPreview styleName="base-nova" name="combobox-invalid" />
|
||||
|
||||
## Disabled
|
||||
|
||||
Use the `disabled` prop to disable the combobox.
|
||||
|
||||
<ComponentPreview styleName="base-nova" name="combobox-disabled" />
|
||||
|
||||
## Auto Highlight
|
||||
|
||||
Use the `autoHighlight` prop to automatically highlight the first item on filter.
|
||||
|
||||
<ComponentPreview styleName="base-nova" name="combobox-auto-highlight" />
|
||||
|
||||
## Popup
|
||||
|
||||
You can trigger the combobox from a button or any other component by using the `render` prop. Move the `ComboboxInput` inside the `ComboboxContent`.
|
||||
|
||||
<ComponentPreview styleName="base-nova" name="combobox-popup" />
|
||||
|
||||
## Input Group
|
||||
|
||||
You can add an addon to the combobox by using the `InputGroupAddon` component inside the `ComboboxInput`.
|
||||
|
||||
<ComponentPreview styleName="radix-nova" name="combobox-input-group" />
|
||||
|
||||
## RTL
|
||||
|
||||
To enable RTL support in shadcn/ui, see the [RTL configuration guide](/docs/rtl).
|
||||
|
||||
<ComponentPreview
|
||||
styleName="radix-nova"
|
||||
name="combobox-rtl"
|
||||
direction="rtl"
|
||||
align="start"
|
||||
/>
|
||||
|
||||
## API Reference
|
||||
|
||||
See the [Base UI](https://base-ui.com/react/components/combobox#api-reference) documentation for more information.
|
||||
Reference in New Issue
Block a user