Combobox

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

Build custom option selection with a combobox store.

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

Use the native useCombobox store and keep Target/Dropdown/Options/Option composition. onOptionSubmit must update business selection as well as close the dropdown.

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);
const combo = M.useCombobox();
return <M.Combobox store={combo} onOptionSubmit={(next) => { setSelection(next); combo.closeDropdown(); }}><M.Combobox.Target><M.Button onClick={() => combo.toggleDropdown()}>{selection ?? "Choose a fruit / 选择水果"}</M.Button></M.Combobox.Target><M.Combobox.Dropdown><M.Combobox.Options>{fruit.map((fruit) => <M.Combobox.Option key={fruit} value={fruit}>{fruit}</M.Combobox.Option>)}</M.Combobox.Options></M.Combobox.Dropdown></M.Combobox>;
}
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.

Examples

This page contains only a small set of examples, as the full code of the demos is long. You can find all 50+ examples on a separate page.

Usage

Combobox provides a set of components and hooks to create custom select, multiselect or autocomplete components. The component is very flexible – you have full control of the rendering and logic.

useCombobox hook

useCombobox hook provides a combobox store. The store contains the current state of the component and handlers to update it. The created store must be passed to the store prop of Combobox:

import { Combobox, useCombobox } from '@mantine/core';

function Demo() {
  const combobox = useCombobox();
  return (
    <Combobox store={combobox}>{/* Your implementation */}</Combobox>
  );
}

useCombobox options

The useCombobox hook accepts an options object with the following properties:

interface UseComboboxOptions {
  /** Default value for `dropdownOpened`, `false` by default */
  defaultOpened?: boolean;

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

  /** Called when `dropdownOpened` state changes */
  onOpenedChange?(opened: boolean): void;

  /** Called when dropdown closes with event source: keyboard, mouse or unknown */
  onDropdownClose?(eventSource: ComboboxDropdownEventSource): void;

  /** Called when dropdown opens with event source: keyboard, mouse or unknown */
  onDropdownOpen?(eventSource: ComboboxDropdownEventSource): void;

  /** Determines whether arrow key presses should loop though items (first to last and last to first), `true` by default */
  loop?: boolean;

  /** `behavior` passed down to `element.scrollIntoView`, `'instant'` by default */
  scrollBehavior?: ScrollBehavior;
}

You can import the UseComboboxOptions type from the @mantine/core package:

import type { UseComboboxOptions } from '@mantine/core';

Combobox store

The Combobox store is an object with the following properties:

interface ComboboxStore {
  /** Current dropdown opened state */
  dropdownOpened: boolean;

  /** Opens dropdown */
  openDropdown(eventSource?: 'keyboard' | 'mouse' | 'unknown'): void;

  /** Closes dropdown */
  closeDropdown(eventSource?: 'keyboard' | 'mouse' | 'unknown'): void;

  /** Toggles dropdown opened state */
  toggleDropdown(
    eventSource?: 'keyboard' | 'mouse' | 'unknown'
  ): void;

  /** Selected option index */
  selectedOptionIndex: number;

  /** Selects `Combobox.Option` by index */
  selectOption(index: number): void;

  /** Selects first `Combobox.Option` with `active` prop.
   *  If there are no such options, the function does nothing.
   */
  selectActiveOption(): string | null;

  /** Selects first `Combobox.Option` that is not disabled.
   *  If there are no such options, the function does nothing.
   * */
  selectFirstOption(): string | null;

  /** Selects next `Combobox.Option` that is not disabled.
   *  If the current option is the last one, the function selects first option, if `loop` is true.
   */
  selectNextOption(): string | null;

  /** Selects previous `Combobox.Option` that is not disabled.
   *  If the current option is the first one, the function selects last option, if `loop` is true.
   * */
  selectPreviousOption(): string | null;

  /** Resets selected option index to -1, removes `data-combobox-selected` from selected option */
  resetSelectedOption(): void;

  /** Triggers `onClick` event of selected option.
   *  If there is no selected option, the function does nothing.
   */
  clickSelectedOption(): void;

  /** Updates selected option index to currently selected or active option.
   *  The function is required to be used with searchable components to update selected option index
   *  when options list changes based on search query.
   */
  updateSelectedOptionIndex(target?: 'active' | 'selected'): void;

  /** List id, used for `aria-*` attributes */
  listId: string | null;

  /** Sets list id */
  setListId(id: string): void;

  /** Ref of `Combobox.Search` input */
  searchRef: React.RefObject<HTMLInputElement | null>;

  /** Moves focus to `Combobox.Search` input */
  focusSearchInput(): void;

  /** Ref of the target element */
  targetRef: React.RefObject<HTMLElement | null>;

  /** Moves focus to the target element */
  focusTarget(): void;
}

You can import ComboboxStore type from @mantine/core package:

import type { ComboboxStore } from '@mantine/core';

useCombobox handlers

Combobox store handlers can be used to control Combobox state. For example, to open the dropdown, call openDropdown handler:

import { Button, Combobox, useCombobox } from '@mantine/core';

function Demo() {
  const combobox = useCombobox();

  return (
    <Combobox>
      <Combobox.Target>
        <Button onClick={() => combobox.openDropdown()}>
          Open dropdown
        </Button>
      </Combobox.Target>

      {/* Your implementation */}
    </Combobox>
  );
}

You can use store handlers in useCombobox options. For example, you can call selectFirstOption when the dropdown is opened and resetSelectedOption when it is closed:

import { Combobox, useCombobox } from '@mantine/core';

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

  return (
    <Combobox store={combobox}>{/* Your implementation */}</Combobox>
  );
}

Combobox.Target

Combobox.Target should be used as a wrapper for the target element or component. Combobox.Target marks its child as a target for dropdown and sets aria-* attributes and adds keyboard event listeners to it.

Combobox.Target requires a single child element or component. The child component must accept ref and ...others props. You can use any Mantine component as a target without any additional configuration, for example, Button, TextInput or InputBase.

Example of using Combobox.Target with TextInput component:

Example of using Combobox.Target with Button component:

Split events and dropdown targets

In some cases, you might need to use different elements as an events target and as a dropdown. Use Combobox.EventsTarget to add aria-* attributes and keyboard event handlers, and Combobox.DropdownTarget to position the dropdown relative to the target.

You can have as many Combobox.EventsTarget as you need, but only one Combobox.DropdownTarget per Combobox.

Example of using Combobox.EventsTarget and Combobox.DropdownTarget with PillsInput component to create a searchable multiselect component:

Update selected option index

updateSelectedOptionIndex handler is required to be called when options list changes. Usually, the options list changes when options are filtered based on the search query. In this case, you need to call updateSelectedOptionIndex in onChange handler of the search input.

Example of using updateSelectedOptionIndex handler in searchable select component:

Search input

If you prefer search input inside the dropdown, use Combobox.Search component. To focus the search input, call combobox.focusSearchInput, usually it is done when the dropdown is opened. To prevent focus loss after the dropdown is closed, call combobox.focusTarget:

Select first option

Use combobox.selectFirstOption function to select the first option. It is useful if you want to select the first option when user searching for options in the list. If there are no options available, it will do nothing.

Active option

Set active prop on Combobox.Option component to mark it as active. By default, an active option does not have any styles, you can use data-combobox-active data attribute to style it.

combobox.selectActiveOption function selects active option. Usually, it is called when the dropdown is opened:

Options groups

Render Combobox.Option components inside Combobox.Group to create options group. Combobox.Group label will be automatically hidden if the group does not have any children.

Scrollable list

Set max-height style on either Combobox.Dropdown or Combobox.Options to make the options list scrollable. You can use mah style prop to set max-height.

Scrollable list with ScrollArea

You can also use ScrollArea or ScrollArea.Autosize components instead of native scrollbars:

Fit dropdown to viewport height

Set floatingHeight="viewport" to make the dropdown grow to fill the available vertical space in the viewport. The dropdown size is recalculated automatically when the trigger position changes. When the prop is set, the flip middleware is disabled – the dropdown always opens in the configured direction and is constrained to the viewport edges instead of flipping to the other side.

The dropdown exposes a --combobox-floating-options-max-height CSS variable equal to the available height minus the dropdown padding. Pass it as mah to your ScrollArea.Autosize (or use it on any element you want to scroll within the bounded dropdown):

Hide dropdown

Set hidden prop on Combobox.Dropdown to hide the dropdown. For example, it can be useful when you want to show the dropdown only when there is at least one option available:

Control dropdown opened state

To control the dropdown opened state, pass opened to useCombobox hook:

Popover props

Combobox supports most of Popover props. For example, you can control dropdown position with position prop and disable Floating UI middlewares with middlewares prop:

Without dropdown

You can use Combobox without dropdown. To do so, use Combobox.EventsTarget instead of Combobox.Target:

Virtualization

useVirtualizedCombobox hook can be used to create comboboxes with virtualized options list. Note that due to the nature of virtualization, the hook requires some additional configuration compared to the useCombobox hook. In useVirtualizedCombobox hook all operations related to option indexing do not rely on the actual DOM structure, instead, you need to preserve values in React state and pass them to the hook.

useVirtualizedCombobox does not depend on any specific virtualization library. The recommended option is @tanstack/react-virtual:

Example of implementation with react-virtuoso:

You can find more virtualization examples on the Combobox examples page.

Hook options:

export interface UseVirtualizedComboboxOptions {
  /** Default value for `dropdownOpened`, `false` by default */
  defaultOpened?: boolean;

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

  /** Called when `dropdownOpened` state changes */
  onOpenedChange?: (opened: boolean) => void;

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

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

  /** Determines whether arrow key presses should loop though items (first to last and last to first), `true` by default */
  loop?: boolean;

  /** Function to determine whether the option is disabled */
  isOptionDisabled?: (optionIndex: number) => boolean;

  /** Total number of options in the virtualized list. Required for proper keyboard navigation and index calculations. */
  totalOptionsCount: number;

  /** Function that returns the id of the option at the given index. Required for setting aria attributes and element references. */
  getOptionId: (index: number) => string | null;

  /** Current selected option index. Must be controlled by parent component. */
  selectedOptionIndex: number;

  /** Callback to update the selected option index. Called when user navigates or selects options. */
  setSelectedOptionIndex: (index: number) => void;

  /** Currently active/highlighted option index. Used to determine which option to select when selectActiveOption is called. */
  activeOptionIndex?: number;

  /** Called when the selected option is submitted (e.g., via Enter key or clicking). Receives the selected option index. */
  onSelectedOptionSubmit: (index: number) => void;
}

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.

Combobox(_props: ComboboxProps)

export type ComboboxStylesNames =
  | 'options'
  | 'dropdown'
  | 'option'
  | 'search'
  | 'empty'
  | 'footer'
  | 'header'
  | 'group'
  | 'groupLabel';

export type ComboboxCSSVariables = {
  options: '--combobox-option-fz' | '--combobox-option-padding';
  dropdown: '--combobox-padding' | '--combobox-option-fz' | '--combobox-option-padding';
};

export interface ComboboxProps extends __PopoverProps, StylesApiProps<ComboboxFactory> {
  __staticSelector?: string;

  /** Combobox content */
  children?: React.ReactNode;

  /** Combobox store, can be used to control combobox state */
  store?: ComboboxStore;

  /** Called when item is selected with the `Enter` key or by clicking it */
  onOptionSubmit?: (value: string, optionProps: ComboboxOptionProps) => void;

  /** Controls items `font-size` and `padding` @default 'sm' */
  size?: MantineSize | (string & {});

  /** Controls `padding` of the dropdown @default 4 */
  dropdownPadding?: React.CSSProperties['padding'];

  /** Determines whether selection should be reset when option is hovered @default false */
  resetSelectionOnOptionHover?: boolean;

  /** Determines whether the `Combobox` value can be changed */
  readOnly?: boolean;

  /** If set to `'viewport'`, the dropdown grows to fill the available vertical space in the viewport. Disables the `flip` middleware. */
  floatingHeight?: 'viewport';
}

export type ComboboxFactory = Factory<{
  props: ComboboxProps;
  ref: HTMLDivElement;
  stylesNames: ComboboxStylesNames;
  vars: ComboboxCSSVariables;
  staticComponents: {
    Target: typeof ComboboxTarget;
    Dropdown: typeof ComboboxDropdown;
    Options: typeof ComboboxOptions;
    Option: typeof ComboboxOption;
    Search: typeof ComboboxSearch;
    Empty: typeof ComboboxEmpty;
    Chevron: typeof ComboboxChevron;
    Footer: typeof ComboboxFooter;
    Header: typeof ComboboxHeader;
    EventsTarget: typeof ComboboxEventsTarget;
    DropdownTarget: typeof ComboboxDropdownTarget;
    Group: typeof ComboboxGroup;
    ClearButton: typeof ComboboxClearButton;
    HiddenInput: typeof ComboboxHiddenInput;
  };
}>;

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.

__PopoverProps
StylesApiProps<ComboboxFactory>
Factory<{
  props: ComboboxProps;
  ref: HTMLDivElement;
  stylesNames: ComboboxStylesNames;
  vars: ComboboxCSSVariables;
  staticComponents: {
    Target: typeof ComboboxTarget;
    Dropdown: typeof ComboboxDropdown;
    Options: typeof ComboboxOptions;
    Option: typeof ComboboxOption;
    Search: typeof ComboboxSearch;
    Empty: typeof ComboboxEmpty;
    Chevron: typeof ComboboxChevron;
    Footer: typeof ComboboxFooter;
    Header: typeof ComboboxHeader;
    EventsTarget: typeof ComboboxEventsTarget;
    DropdownTarget: typeof ComboboxDropdownTarget;
    Group: typeof ComboboxGroup;
    ClearButton: typeof ComboboxClearButton;
    HiddenInput: typeof ComboboxHiddenInput;
  };
}>
HTMLDivElement
React.ReactNode
ComboboxStore
ComboboxOptionProps
MantineSize
React.CSSProperties