JGuang
EN

组合框弹层

ComboboxPopover · Mantine Core

交互预览
npm install @mantine/core@9.7.1 @mantine/hooks@9.7.1

组合框弹层

Mantine Core 的独立组件，请不要替换为 JGuang UI/Base UI 的同名 API。

安装

npm install @mantine/core@9.7.1 @mantine/hooks@9.7.1

入口引入 @mantine/core/styles.css，并在根组件使用 MantineProvider；通过 forceColorScheme 同步深浅色主题。

使用与验证

在左侧选择组件，在预览中操作它的状态；使用“查看代码”检查真实源码。安装后执行类型检查和构建，再验证键盘焦点、手机布局与深浅色主题。

来源

https://github.com/mantinedev/mantine/tree/f0e2bc6d28b0f0b8aaefb5b859937bf77f539df7 MIT 许可证；不包括付费内容。下方提供上游英文参考内容，中文使用指南已适配；上游详细参考暂保留英文。

版本与兼容性

固定的 Mantine Core 9.7.1 要求 React 和 React DOM 满足 ^19.2.0，并配套 @mantine/hooks@9.7.1。此条件来自实际 npm 包的 peerDependencies。React 18 或其他不兼容版本不能强行安装；先向项目负责人说明升级影响并确认方案，不使用 --force/--legacy-peer-deps 掩盖冲突。入口的原生 Provider 开启 theme.respectReducedMotion，并用 forceColorScheme 控制深浅色。

适用场景

在气泡弹层内组合可搜索选择器。

本地示例使用的原生参数

以下参数由本地、经过类型检查的 JSX 示例提取，按所属组件区分。不是全部属性清单；完整签名和继承关系见下方固定源码参考。

组件参数说明
ComboboxPopover.data本地选项或节点，保持 value 唯一并遵循原生结构。
ComboboxPopover.searchable启用当前组件的本地搜索交互。
ComboboxPopover.value受控值，具体结构由原生类型定义。
ComboboxPopover.onChange原生值或事件回调，保留实际函数签名。

交互与状态检查

当前场景：默认。切换支持的禁用、错误或只读场景后检查真实行为；无此原生状态的组件不会被强行添加统一属性。验证键盘焦点和退出方式，修改值后按原生回调签名连接业务状态。

业务接入边界

Target 必须接受触发器传入的 props/ref。除非宿主提供远程数据，否则搜索只在本地执行。

宿主配置

先安装固定版本 @mantine/core 和 @mantine/hooks，在入口引入 @mantine/core/styles.css，并使用 MantineProvider。示例的 theme 和 variant 是 JGuang 编写的宿主参数，不是所有原生组件都接受的统一 API；通过 forceColorScheme 同步应用主题。源码面板中的原生实现仅供阅读，使用 npm 导出，不要单独复制内部实现。此批只覆盖 Core，不包括日期、图表和表单扩展包。上游详细说明保留英文，不宣称全文中文化。

可运行用法

以下代码使用资源原生 API；不是把其他设计系统的同名组件替换进来。

import { useState } from 'react';
import * as M from '@mantine/core';
import '@mantine/core/styles.css';

const fruit = ["Apple", "Banana", "Orange"];
function ComponentPreview({ variant = 'Default' }: { variant?: string }) {
const [value, setValue] = useState(35);
const [selection, setSelection] = useState<string | null>(null);
return <M.ComboboxPopover data={fruit} searchable value={selection} onChange={setSelection}><M.ComboboxPopover.Target><M.Button>{selection ?? "Choose a fruit / 选择水果"}</M.Button></M.ComboboxPopover.Target></M.ComboboxPopover>;
}
export default function Example({ variant = 'Default', theme = 'light' }: { variant?: string; theme?: 'light' | 'dark' }) {
return <M.MantineProvider forceColorScheme={theme} theme={{ respectReducedMotion: true }}><ComponentPreview variant={variant} /></M.MantineProvider>;
}

可用状态与示例

默认

示例遵循 Mantine 原生 API。支持多状态的输入组件可将示例中的 variant 改为 Disabled、Invalid 或 Read only；这些只是示例标签，不是新增的组件属性。改造时保留组件要求的数据、受控值、store 和复合子组件结构。

Usage

ComboboxPopover adds a dropdown with selectable options to any button. Unlike Select and MultiSelect, it does not render an input: pass your own target element to ComboboxPopover.Target. The target must be a single element or component that accepts a ref.

Data format

ComboboxPopover supports the same data format as Select component: an array of strings, objects with value and label, or grouped items.

Searchable

Set searchable prop to add a search input to the dropdown:

Controlled search value

Use searchValue and onSearchChange props to control the search input value:

Sort options

Use filter prop with searchable to provide a custom filtering and sorting function:

Limit options

Use limit prop with searchable to limit the number of options displayed at a time:

Multiple selection

Set multiple prop to allow selecting multiple values. value type changes from string | null to string[].

Check icon

Allow deselect

By default, the selected option can be deselected by clicking it again. Set allowDeselect={false} to prevent this behavior.

Nothing found message

Set nothingFoundMessage prop to display a message when no options are available:

Disabled options

Groups

Render option

Use renderOption prop to customize option rendering:

Large data sets

By default, the dropdown is wrapped with ScrollArea.Autosize. Use maxDropdownHeight to control the maximum height:

Control dropdown opened state

Use dropdownOpened, onDropdownOpen and onDropdownClose props to control the dropdown state:

By default, the dropdown width matches the target element. Use comboboxProps to set a custom width:

Form submission

ComboboxPopover renders a hidden input with the selected value for native form submission. Use name prop to set the input name. For multiple selection, values are joined with a comma by default – use hiddenInputValuesDivider to change the separator.

源码参数参考

以下实现签名和类型从本地固定版本源码生成。保留可选属性、原生继承类型、联合分支和 never 限制；不会将其他设计系统的 API 混入。forwardRef 实现中的 ref 属于 React 引用，不是新增业务属性。此区域是原始类型参考，不是上游说明的全文翻译。

ComboboxPopover(_props)

export type ComboboxPopoverStylesNames = ComboboxLikeStylesNames | 'search';

export interface ComboboxPopoverProps<
  Multiple extends boolean = false,
  Value extends Primitive = string,
> extends StylesApiProps<ComboboxPopoverFactory> {
  /** If set, multiple items can be selected at the same time */
  multiple?: Multiple;

  /** Controlled component value */
  value?: ComboboxPopoverValue<Multiple, Value>;

  /** Uncontrolled component default value */
  defaultValue?: ComboboxPopoverValue<Multiple, Value>;

  /** Called when value changes */
  onChange?: (value: ComboboxPopoverValue<Multiple, Value>) => void;

  /** Data used to generate options */
  data?: ComboboxData<Value>;

  /** Controlled dropdown opened state */
  dropdownOpened?: boolean;

  /** Uncontrolled dropdown initial opened state */
  defaultDropdownOpened?: boolean;

  /** Called when dropdown opens */
  onDropdownOpen?: () => void;

  /** Called when dropdown closes */
  onDropdownClose?: () => void;

  /** Called when option is submitted from dropdown with mouse click or Enter key */
  onOptionSubmit?: (value: Value) => void;

  /** Props passed down to Combobox component */
  comboboxProps?: ComboboxProps;

  /** Function based on which items are filtered and sorted */
  filter?: OptionsFilter<Value>;

  /** Maximum number of options displayed at a time @default Infinity */
  limit?: number;

  /** Determines whether the options should be wrapped with ScrollArea.AutoSize @default true */
  withScrollArea?: boolean;

  /** max-height of the dropdown @default 220 */
  maxDropdownHeight?: number | string;

  /** If set, the first option is selected when dropdown opens @default false */
  selectFirstOptionOnDropdownOpen?: boolean;

  /** Displays check icon near the selected option label @default true */
  withCheckIcon?: boolean;

  /** Aligns unchecked labels with the checked one @default false */
  withAlignedLabels?: boolean;

  /** Position of the check icon relative to the option label @default 'left' */
  checkIconPosition?: 'left' | 'right';

  /** Message displayed when no options match the search query or when there is no data */
  nothingFoundMessage?: React.ReactNode;

  /** Allows searching through options @default false */
  searchable?: boolean;

  /** Controlled search value */
  searchValue?: string;

  /** Default search value */
  defaultSearchValue?: string;

  /** Called when search changes */
  onSearchChange?: (value: string) => void;

  /** Allows deselecting the selected option by clicking it (only for single mode) @default true */
  allowDeselect?: boolean;

  /** A function to render content of the option, replaces the default content of the option */
  renderOption?: (item: ComboboxLikeRenderOptionInput<ComboboxItem>) => React.ReactNode;

  /** Props passed down to the underlying ScrollArea component in the dropdown */
  scrollAreaProps?: ScrollAreaProps;

  /** Props passed down to the hidden input */
  hiddenInputProps?: Omit<React.ComponentProps<'input'>, 'value'>;

  /** Hidden input name for form submission */
  name?: string;

  /** Hidden input form for form submission */
  form?: string;

  /** Content of the component */
  children?: React.ReactNode;

  /** Divider used to separate values in the hidden input value attribute @default ',' */
  hiddenInputValuesDivider?: string;
}

export type ComboboxPopoverFactory = Factory<{
  props: ComboboxPopoverProps;
  ref: HTMLDivElement;
  stylesNames: ComboboxPopoverStylesNames;
  signature: <Multiple extends boolean = false, Value extends Primitive = string>(
    props: ComboboxPopoverProps<Multiple, Value>
  ) => React.JSX.Element;
  staticComponents: {
    Target: typeof ComboboxPopoverTarget;
  };
}>;

原生与外部类型

以下外部类型仍由 React 或资源自身依赖定义，没有手工展开为虚构属性。实际可用类型以安装版本的 TypeScript 检查为准。

Factory<{
  props: ComboboxPopoverProps;
  ref: HTMLDivElement;
  stylesNames: ComboboxPopoverStylesNames;
  signature: <Multiple extends boolean = false, Value extends Primitive = string>(
    props: ComboboxPopoverProps<Multiple, Value>
  ) => React.JSX.Element;
  staticComponents: {
    Target: typeof ComboboxPopoverTarget;
  };
}>
Primitive
StylesApiProps<ComboboxPopoverFactory>
Multiple
ComboboxPopoverValue<Multiple, Value>
Value
ComboboxData<Value>
ComboboxProps
OptionsFilter<Value>
React.ReactNode
ComboboxLikeRenderOptionInput<ComboboxItem>
ComboboxItem
ScrollAreaProps
Omit<React.ComponentProps<'input'>, 'value'>
React.ComponentProps<'input'>
HTMLDivElement
ComboboxLikeStylesNames
React.JSX.Element