mantine-combobox

Mantine Combobox 技能

适用于 Mantine 9.x。

概览

Combobox 提供用于构建各种类选择器界面的底层原语。内置的 Select、MultiSelect、Autocomplete 和 TagsInput 组件都是基于它构建的。

请先检查是否有现成组件

只有在以下组件都不适用时，才使用 Combobox 原语进行构建：

需求	使用
标准选择器、多选器、自动补全或标签输入框	Select、MultiSelect、Autocomplete、TagsInput（均支持 renderOption）
附加到按钮或其他元素的选项下拉菜单，无输入框	ComboboxPopover（数据驱动：data、value、onChange、searchable、multiple）
层级选项	TreeSelect（见下文）
选项超过几百个	搭配 useVirtualizedCombobox 使用 Combobox，参见虚拟化模式

<ComboboxPopover data={['React', 'Angular', 'Vue']} value={value} onChange={setValue}>
  <ComboboxPopover.Target>
    <Button variant="default">{value || 'Select framework'}</Button>
  </ComboboxPopover.Target>
</ComboboxPopover>

ComboboxPopover 会在目标元素被点击时自行打开，以勾选图标标记所选选项，并处理键盘导航。实用属性：searchable、multiple（值变为 string[]，选择时下拉菜单保持打开）、allowDeselect={false}（始终选中一个选项）、nothingFoundMessage、renderOption、limit、maxDropdownHeight、name（用于表单的隐藏输入框）、comboboxProps={{ width: 220, position: 'bottom-start' }}。data 支持禁用项和分组，格式与 Select 相同：[{ group: 'Size', items: [{ value: 'xs', label: 'XS' }] }]。它无法渲染自定义下拉内容（标签页、页眉、页脚、创建操作）；如需这些内容，请使用 Combobox 原语。

TreeSelect 接收嵌套的 data（{ value, label, children? }[]，值必须唯一），并在下拉菜单中显示带可展开树结构的输入框。属性包括 mode（单选、多选，或支持父子级联的复选框模式）、searchable、clearable、renderNode。如果需要不同的布局，请改用 Combobox 原语构建树，例如仅允许选择叶节点、将搜索结果以包含完整路径的平面列表显示，或使用按钮触发器。这种情况下，将每个可见行渲染为 Combobox.Option，并在 onOptionSubmit 中决定该行是用于选择还是展开。

核心工作流

1. 创建 store

const combobox = useCombobox({
  onDropdownClose: () => combobox.resetSelectedOption(),
  onDropdownOpen: () => combobox.selectFirstOption(),
});

2. 渲染结构

<Combobox store={combobox} onOptionSubmit={handleSubmit}>
  <Combobox.Target targetType="button">
    <InputBase
      component="button"
      type="button"
      pointer
      rightSection={<Combobox.Chevron />}
      onClick={() => combobox.toggleDropdown()}
    >
      {value || <Input.Placeholder>Pick value</Input.Placeholder>}
    </InputBase>
  </Combobox.Target>
  <Combobox.Dropdown>
    <Combobox.Options>
      {options.map((item) => (
        <Combobox.Option value={item} key={item}>{item}</Combobox.Option>
      ))}
    </Combobox.Options>
  </Combobox.Dropdown>
</Combobox>

3. 处理提交

const handleSubmit = (val: string) => {
  setValue(val);
  combobox.closeDropdown();
};

目标类型

场景	使用
按钮触发器（无文本输入）	<Combobox.Target targetType="button">
输入框触发器	<Combobox.Target>（默认）
胶囊标签 + 独立输入框（多选）	<Combobox.DropdownTarget> + <Combobox.EventsTarget>

Combobox 能为你做什么

• 目标元素负责处理键盘操作：ArrowUp/ArrowDown 移动高亮项并跳过禁用选项（下拉框关闭时也会将其打开），Enter 提交高亮选项，Escape 关闭下拉框。使用 targetType="button" 时，Space 和 Enter 也会打开下拉框。Tab 不会被处理。
• 未高亮任何选项时，按 Enter 不会执行任何操作，因此自由文本输入框可以自行处理该按键。
• 用户按下方向键之前，不会高亮任何选项；除非你调用 selectFirstOption() 或 selectActiveOption()。
• 点击选项不会让焦点离开输入框，禁用选项也绝不会调用 onOptionSubmit。
• Combobox.Option 会将 data-* 属性和事件处理程序转发给其元素。
• Combobox.Search 处理与目标元素相同的按键。目标子元素或 Combobox.Search 上自定义的 onKeyDown 会先被调用，然后才运行内置处理，因此可以在那里添加额外按键处理（PageUp、ArrowRight）。若要完全接管键盘操作（例如在文本区域中，方向键必须移动插入光标），请在 Combobox.Target 上设置 withKeyboardNavigation={false}，并自行调用 selectNextOption、selectPreviousOption 和 clickSelectedOption。
• 默认行为：下拉框宽度与目标元素相同（width="target"），在 portal 中渲染，关闭时仍保持挂载，打开时无动画，悬停选项不会改变键盘高亮项。
• 下拉框会在模态框和抽屉上方的 portal 中渲染，不会被它们裁切。在 Modal 中，按 Escape 只会关闭下拉框；再次按 Escape 才会关闭模态框。无需额外代码。
• 选项不必用于选择值：onOptionSubmit 可以切换状态、展开行或执行操作，并由它自行决定是否关闭下拉框。
• 下拉框中的其他交互内容（Combobox.Header 中的按钮、重试链接）不会被处理：请为它们添加 onMouseDown={(event) => event.preventDefault()}，这样输入框就能保持焦点，onBlur 处理程序也不会关闭下拉框。

两个容易混淆的词：

• 已选中选项：由键盘导航高亮的选项（data-combobox-selected）。
• 活动选项：当前值对应的选项，通过 active 属性标记（data-combobox-active）。默认没有样式：请渲染一个勾选图标。

参考资料

在构建超出上述基础选择器的内容之前，请先阅读这两份资料：

• references/patterns.md — 完整示例：可搜索选择器（输入框触发）、带建议项的自由文本输入框、文本区域的建议项（提及）、使用 CSS module 的自定义样式、包含数千个选项的虚拟化列表、基于 Combobox 构建的自定义表单输入、下拉框内搜索、带标签的多选、可创建选项、带加载和错误状态的异步搜索、分组、自定义选项渲染、打开时高亮当前值、清除按钮、表单集成、适配视口的下拉框
• references/api.md — useCombobox 的选项以及所有 store 方法及其功能、默认样式及其覆盖方式、useVirtualizedCombobox、所有子组件属性、CSS 变量、Styles API 选择器

查找资料

如果参考资料没有涵盖你需要的内容，请勿猜测：

• 如果已连接 Mantine MCP 服务（@mantine/mcp-server），请使用 search_docs 和 get_item_doc
• 否则，请获取 https://mantine.dev/llms.txt 并打开 Combobox 页面。https://mantine.dev/combobox/ 上有 50 多个完整示例