组合框

一个输入框，搭配一组预定义选项供用户选择。

安装


pnpm dlx shadcn@latest add @lumi-ui/combobox

组件结构

<Combobox>
  <ComboboxTrigger />
  <ComboboxInputGroupContent />
 
  <ComboboxChips>
    <ComboboxChip />
  </ComboboxChips>
 
  <ComboboxContent>
    <ComboboxStatus />
    <ComboboxEmpty />
    <ComboboxList>
      <ComboboxRow>
        <ComboboxItemContent />
      </ComboboxRow>
      <ComboboxSeparator />
      <ComboboxGroup>
        <ComboboxGroupLabel />
      </ComboboxGroup>
      <ComboboxCollection />
    </ComboboxList>
  </ComboboxContent>
</Combobox>

功能特性

带清除按钮、触发按钮和图标

输入框置于弹窗内

使用 ComboboxTrigger 替代 ComboboxInputGroup，可将输入框放入弹窗内。在 ComboboxInput 上设置 variant="ghost" 以去除边框和聚焦样式。

修改指示器图标及位置

分组

自定义锚点 (positionerAnchor)

ComboboxContent 默认以 ComboboxTrigger 作为锚点。如果你希望弹窗宽度与外层容器一致，可以手动将该容器指定为锚点。

实用示例

配合滚动区域

多选

可创建选项

异步加载（单选）

异步加载（多选）

自定义样式

表单集成

API 参考

ComboboxInputGroup

一个高阶的输入组件，它将 ComboboxInput、Icon、ComboboxClear 和 ComboboxTrigger 整合为一个带样式的单一元素。

属性	类型	描述
`showTrigger`	`boolean`	是否显示触发器图标。
`showClear`	`boolean`	是否显示清除图标。
`addonIcon`	`React.ReactNode`	是否显示附加图标。
`variant`	`"ghost" \| "default" \| "transparent"`	输入框组的视觉变体。
`inputSize`	`"default" \| "sm" \| "lg"`	输入框的尺寸。
`className`	`string`	额外的 CSS 类名。
`...props`	`ComboboxInput.Props`	将所有其他属性传递给底层的 `ComboboxInput.Props`。

ComboboxContent

一个高阶的容器组件，它将 ComboboxPortal、ComboboxPositioner 和 ComboboxPopup 整合为一个带样式的下拉内容元素。

属性	类型	描述
`sideOffset`	`number`	相对于锚点的偏移距离。
`align`	`"start" \| "center" \| "end"`	相对于锚点的对齐方式。
`matchAnchorWidth`	`boolean`	弹窗宽度是否与锚点宽度保持一致。
`positionerAnchor`	`React.RefObject<HTMLDivElement \| null>`	传递给定位器的 ref，用于自定义锚定。
`className`	`string`	额外的 CSS 类名。
`...props`	`ComboboxPopup.Props`	将所有其他属性传递给底层的 `ComboboxPopup.Props`。

ComboboxItemContent

一个高阶的选项组件，它将 Item 和 ItemIndicator 整合为一个带样式的单一元素，并可配置图标位置。

属性	类型	描述
`indicatorPlacement`	`"start" \| "end" \| "none"`	指示器图标相对于内容的位置。
`indicatorIcon`	`React.ReactNode`	用作选项指示器的图标。
`className`	`string`	额外的 CSS 类名。
`...props`	`ComboboxItem.Props`	将所有其他属性传递给底层的 `ComboboxItem.Props`。