🌐 Nodejs.cn
新建

组合框

PreviousNext

带有建议列表的自动补齐输入。

Radix UIBase UI
Radix UI
"use client"

import {

安装

🌐 Installation

pnpm dlx shadcn@latest add combobox

用法

🌐 Usage

import {
  Combobox,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
} from "@/components/ui/combobox"
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>
  )
}

自定义条目

🌐 Custom Items

当你的项目是对象时，使用 itemToStringValue。

🌐 Use itemToStringValue when your items are objects.

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

使用 multiple 配合 chip 实现多选行为。

🌐 Use multiple with chips for multi-select behavior.

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>
  )
}

示例

🌐 Examples

基础

🌐 Basic

一个带有框架列表的简单下拉框。

🌐 A simple combobox with a list of frameworks.

"use client"

import {

多个

🌐 Multiple

使用 multiple 和 ComboboxChips 的多选组合框。

🌐 A combobox with multiple selection using multiple and ComboboxChips.

"use client"

import * as React from "react"

清除按钮

🌐 Clear Button

使用 showClear 属性来显示一个清除按钮。

🌐 Use the showClear prop to show a clear button.

"use client"

import {

群组

🌐 Groups

使用 ComboboxGroup 和 ComboboxSeparator 来分组项目。

🌐 Use ComboboxGroup and ComboboxSeparator to group items.

"use client"

import {

自定义条目

🌐 Custom Items

你可以在 ComboboxItem 内渲染自定义组件。

🌐 You can render custom component inside ComboboxItem.

"use client"

import {

无效

🌐 Invalid

使用 aria-invalid 属性使组合框无效。

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

"use client"

import {

已禁用

🌐 Disabled

使用 disabled 属性来禁用组合框。

🌐 Use the disabled prop to disable the combobox.

"use client"

import {

自动高亮

🌐 Auto Highlight

使用 autoHighlight 属性自动高亮筛选器中的第一个项目。

🌐 Use the autoHighlight prop automatically highlight the first item on filter.

"use client"

import {

弹出窗口

🌐 Popup

你可以通过使用 render 属性从按钮或任何其他组件触发下拉框。将 ComboboxInput 移动到 ComboboxContent 内部。

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

"use client"

import { Button } from "@/components/ui/button"

输入组

🌐 Input Group

你可以通过在 ComboboxInput 内使用 InputGroupAddon 组件来向组合框添加一个插件。

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

"use client"

import {

从右到左

🌐 RTL

要在 shadcn/ui 中启用 RTL 支持，请参阅 RTL 配置指南。

🌐 To enable RTL support in shadcn/ui, see the RTL configuration guide.

"use client"

import * as React from "react"

API参考

🌐 API Reference

有关更多信息，请参见 Base UI 文档。

🌐 See the Base UI documentation for more information.