Combobox

输入时给出建议的文本框：沿用 Input 的输入框，带清除按钮与下拉箭头；下方弹出的面板与选项行沿用 Select。

安装

terminal

# once per project: where @zzzui items come frompnpm dlx shadcn@latest registry add @zzzui=https://zzzui.catforest.dev/r/{name}.jsonpnpm dlx shadcn@latest add @zzzui/combobox

示例

选择街区

combobox-district.tsx

import {  Combobox,  ComboboxContent,  ComboboxEmpty,  ComboboxInput,  ComboboxItem,  ComboboxList,} from "@/components/zero/combobox";const districts = [  { value: "harbor", label: "Harbor" },  { value: "rail-yards", label: "Rail yards" },  { value: "old-market", label: "Old market" },  { value: "canal-docks", label: "Canal docks" },  { value: "tower-9", label: "Tower 9" },  { value: "north-gate", label: "North gate" },];export default function ComboboxDistrict() {  return (    <div className="w-full max-w-xs">      <Combobox items={districts}>        <ComboboxInput placeholder="Pick a district" aria-label="District" />        <ComboboxContent>          <ComboboxEmpty>No district by that name.</ComboboxEmpty>          <ComboboxList>            {(item: (typeof districts)[number]) => (              <ComboboxItem key={item.value} value={item}>                {item.label}              </ComboboxItem>            )}          </ComboboxList>        </ComboboxContent>      </Combobox>    </div>  );}

多选街区，以斜切块呈现

combobox-districts.tsx

import {  Combobox,  ComboboxChip,  ComboboxChips,  ComboboxChipsInput,  ComboboxContent,  ComboboxEmpty,  ComboboxItem,  ComboboxList,  ComboboxValue,} from "@/components/zero/combobox";type District = { value: string; label: string };const districts: District[] = [  { value: "harbor", label: "Harbor" },  { value: "rail-yards", label: "Rail yards" },  { value: "old-market", label: "Old market" },  { value: "canal-docks", label: "Canal docks" },  { value: "tower-9", label: "Tower 9" },  { value: "north-gate", label: "North gate" },];export default function ComboboxDistricts() {  return (    <div className="w-full max-w-sm">      <Combobox items={districts} multiple defaultValue={[districts[0]]}>        <ComboboxChips>          <ComboboxValue>            {(value: District[]) => (              <>                {value.map((district) => (                  <ComboboxChip key={district.value}>                    {district.label}                  </ComboboxChip>                ))}                <ComboboxChipsInput                  aria-label="Districts"                  placeholder={value.length > 0 ? "" : "Pick districts"}                />              </>            )}          </ComboboxValue>        </ComboboxChips>        <ComboboxContent>          <ComboboxEmpty>No district by that name.</ComboboxEmpty>          <ComboboxList>            {(item: District) => (              <ComboboxItem key={item.value} value={item}>                {item.label}              </ComboboxItem>            )}          </ComboboxList>        </ComboboxContent>      </Combobox>    </div>  );}

行为

输入文字即筛选列表；高亮行填充强调色，已选项带斜切标记。将条目传给 Combobox，并在 ComboboxList 的函数子元素中逐项渲染。

设置 multiple 后，已选项以小号斜切块显示在输入框内（ComboboxChips、ComboboxChip、ComboboxChipsInput），每块带一个移除按钮。输入框内的斜切块会自动换行，因此输入框采用 Textarea 的直角样式。光标位于文字开头时按 Backspace，可移除最后一项。

属性

Combobox

属性	类型	默认值	说明
items	Item[]	—	可供建议的条目，每项都需要 label。
value / onValueChange	Item \| null	—	已选项，受控。

另可传入 Base UI Combobox.Root 的全部属性。

ComboboxInput

属性	类型	默认值	说明
size	"sm" \| "md" \| "lg"	"md"	与 Input 相同的高度。
cut	"end" \| "start" \| "both" \| "none"	"end"	斜切位置：末端、起始端、两端或不斜切。
showClear	boolean	true	是否显示清除按钮。
labels	{ clear?: string; show?: string }	"Clear" / "Show suggestions"	两个小按钮的可访问名称。

ComboboxContent, ComboboxList, ComboboxItem, ComboboxEmpty, ComboboxGroup, ComboboxLabel, ComboboxSeparator, ComboboxChips, ComboboxChip, ComboboxChipsInput

另可传入 Base UI Combobox.Popup 的全部属性。

ComboboxChip

属性	类型	默认值	说明
removeLabel	string	"Remove"	已选项上移除按钮的可访问名称。