Create custom select, autocomplete or multiselect inputs
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 .
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 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 :
The useCombobox hook accepts an options object with the following properties:
You can import the UseComboboxOptions type from the @mantine/core package:
The Combobox store is an object with the following properties:
You can import ComboboxStore type from @mantine/core package:
Combobox store handlers can be used to control Combobox state. For example, to open the dropdown, call openDropdown handler:
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:
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:
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:
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:
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 :
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.
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:
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.
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 .
You can also use ScrollArea or ScrollArea.Autosize components instead of native scrollbars:
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):
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:
To control the dropdown opened state, pass opened to useCombobox hook:
Dropdown is opened/closed when button is clicked
Combobox supports most of Popover props. For example, you can control dropdown position with position prop and disable Floating UI middlewares with middlewares prop:
You can use Combobox without dropdown. To do so, use Combobox.EventsTarget instead of Combobox.Target :
Combobox supports the Styles API ; you can add styles to any inner element of the component with the classNames prop. Follow the Styles API documentation to learn more.
Component Styles API
Hover over selectors to highlight corresponding elements
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 .