Select

import { SelectDemos } from '@docs/demos'; import { Layout } from '@/layout'; import { MDX_DATA } from '@/mdx';

export default Layout(MDX_DATA.Select);

Usage

Select allows capturing user input based on suggestions from a list. Unlike Autocomplete, Select does not allow entering custom values.

Loading state

Set loading prop to display a loading indicator. By default, the loader is displayed on the right side of the input. This is useful for async operations like API calls, searches, or validations:

Controlled

The Select value must be a primitive type (string, number, or boolean). The onChange function is called with a primitive value as a single argument.

tsx

import { useState } from 'react';
import { Select } from '@mantine/core';

function Demo() {
  const [value, setValue] = useState<string | null>('');
  return <Select data={[]} value={value} onChange={setValue} />;
}

onChange handler

onChange is called with two arguments:

value - string value of the selected option
option – selected option object

If you prefer the object format in state, use the second argument of the onChange handler:

tsx

import { useState } from 'react';
import { ComboboxItem, Select } from '@mantine/core';

function Demo() {
  const [value, setValue] = useState<ComboboxItem | null>(null);
  return (
    <Select
      data={[{ value: 'react', label: 'React library' }]}
      value={value ? value.value : null}
      onChange={(_value, option) => setValue(option)}
    />
  );
}

autoSelectOnBlur

Set the autoSelectOnBlur prop to automatically select the highlighted option when the input loses focus. Note: This prop only has an effect when searchable is set to true. To see this feature in action: select an option with the up/down arrows, then click outside the input:

Clearable

Set the clearable prop to display the clear button in the right section. The button is not displayed when:

The component does not have a value
The component is disabled
The component is read only

Allow deselect

The allowDeselect prop determines whether the value should be deselected when the user clicks on the selected option. By default, allowDeselect is true:

Open on focus

Set the openOnFocus prop to open the dropdown when the input receives focus. Note: This prop only has an effect when searchable is set to true:

Searchable

Set the searchable prop to allow filtering options by user input:

Controlled search value

You can control the search value with searchValue and onSearchChange props:

tsx

import { useState } from 'react';
import { Select } from '@mantine/core';

function Demo() {
  const [searchValue, setSearchValue] = useState('');
  return (
    <Select
      searchable
      searchValue={searchValue}
      onSearchChange={setSearchValue}
      data={[]}
    />
  );
}

Nothing found

Set the nothingFoundMessage prop to display a given message when no options match the search query or there is no data available. If the nothingFoundMessage prop is not set, the Select dropdown will be hidden.

Checked option icon

Set checkIconPosition prop to left or right to control position of check icon in active option. To remove the check icon, set withCheckIcon={false}. To align unchecked labels with the checked one, set withAlignedLabels prop.

Value type

Select supports primitive values (strings, numbers, booleans) as value type. Select automatically infers the value type. If you want to set the value type explicitly, pass type argument:

tsx

import { Select } from '@mantine/core';

type SelectValue = 'React' | 'Angular' | 'Svelte' | number;

function Demo() {
  return <Select<SelectValue> data={['React', 'Angular', 'Svelte', 100]} />;
}

Sort options

By default, options are sorted by their position in the data array. You can change this behavior with the filter function:

Fuzzy search with fuse.js

You can implement fuzzy search using the fuse.js library to match options even with typos or partial matches:

renderOption

The renderOption callback allows you to customize option rendering. It is called with an option object and checked state. The function must return a React node.

By default, the options list is wrapped with ScrollArea.Autosize. You can control the dropdown max-height with the maxDropdownHeight prop if you do not change the default settings.

If you want to use native scrollbars, set withScrollArea={false}. Note that in this case, you will need to change the dropdown styles with Styles API.

Set floatingHeight="viewport" to make the dropdown grow to fill the available vertical space in the viewport. The flip middleware is disabled in this mode – the dropdown always opens in the configured direction and is constrained to the viewport edges instead of flipping to the other side. Useful when working with large option lists:

Group options

The group property accepts any React node, so you can render custom markup (icons, badges, styled text) as a group label instead of a plain string. This also applies to MultiSelect, Autocomplete and TagsInput. Note that NativeSelect renders native optgroup elements and only supports string group labels.

Disabled options

When an option is disabled, it cannot be selected and is ignored in keyboard navigation.

To use Select inside popover, you need to set withinPortal: false:

You can control the dropdown opened state with the dropdownOpened prop. Additionally, you can use onDropdownClose and onDropdownOpen to listen to dropdown opened state changes.

By default, the dropdown is displayed below the input if there is enough space; otherwise it is displayed above the input. You can change this behavior by setting the position and middlewares props, which are passed down to the underlying Popover component.

Example of a dropdown that is always displayed above the input:

To change the dropdown width, set the width prop in comboboxProps. By default, the dropdown width is equal to the input width.

To change the dropdown offset, set the offset prop in comboboxProps:

Prevent horizontal infinite scrolling

If you experience horizontal infinite scrolling in the dropdown, set the shift middleware padding to 0:

tsx

import { Select } from '@mantine/core';

function Demo() {
  return (
    <Select
      data={['React', 'Angular', 'Vue']}
      comboboxProps={{
        middlewares: {
          shift: { padding: 0 }
        }
      }}
    />
  );
}

By default, dropdown animations are disabled. To enable them, you can set transitionProps, which will be passed down to the underlying Transition component.

Input props

Read only

Set readOnly to make the input read only. When readOnly is set, Select will not show suggestions and will not call the onChange function.

Disabled

Set disabled to disable the input. When disabled is set, the user cannot interact with the input and Select will not show suggestions.

Error state

Success state

To set aria-label on the clear button, use clearButtonProps. Note that this is required only when clearable is set.

tsx

import { Select } from '@mantine/core';

function Demo() {
  return (
    <Select
      data={[]}
      clearable
      clearButtonProps={{
        'aria-label': 'Clear input',
      }}
    />
  );
}