ComboboxPopover

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

Version and compatibility

Pinned Mantine Core 9.7.1 requires React and React DOM ^19.2.0 and matching @mantine/hooks@9.7.1, from the installed npm package's peerDependencies. Do not force it into React 18 or another incompatible version. Explain upgrade impact and agree on a plan with the project owner; do not hide conflicts with --force/--legacy-peer-deps. The native Provider enables theme.respectReducedMotion and uses forceColorScheme for light/dark.

Use case

Compose a searchable selection inside a popover.

Native props used by this example

These props are extracted from the local typechecked JSX and grouped by their owning native component. This is not an exhaustive prop list; see pinned source signatures and inheritance below.

Interaction and state checks

Current scenarios: Default. Check actual behavior after selecting supported disabled/error/read-only scenarios; components without those native states do not receive invented universal props. Verify keyboard focus and exits, then connect changed values through the native callback signature.

Business integration boundary

Target must accept the trigger's forwarded props/ref. Search is local unless the host supplies remote data.

Host setup

Install pinned @mantine/core and @mantine/hooks, import @mantine/core/styles.css at the entry and use MantineProvider. The example's theme/variant are JGuang-authored host props, not universal native component APIs; forceColorScheme synchronizes the app theme. Native implementation source is a reading reference: use npm exports rather than copying internal engines. This batch covers Core, not dates/charts/forms extension packages. Detailed upstream prose remains English.

Runnable usage

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

Preview states

Default

The example uses the native Mantine API. For supported input demos, change the local variant to Disabled, Invalid or Read only; these are example labels, not new component props. Keep the documented data, controlled values, stores and compound children when adapting the example.

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:

Dropdown position

Dropdown width

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

Dropdown animation

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.

Source-backed parameter reference

Implementation signatures and types are generated from the pinned local source. Optional props, native inherited types, union branches and never exclusions are preserved. A forwardRef implementation's ref is a React reference, not an additional business prop.

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

Native and external types

External types remain defined by React or native dependencies, not manually expanded into guessed props. The installed version's TypeScript definitions are authoritative.

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