Mantine UIFAQColors generator

Select

Custom searchable select

Source

View source code

LLM docs

LLM documentation

Docs

Edit this page

PackageIcon

@mantine/core

Made with Combobox

Select is an opinionated component built on top of the Combobox component. It has a limited set of features to cover only basic use cases. If you need more advanced features, you can build your own component with Combobox. You can find examples of custom select components on the examples page.

Usage

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

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

function Demo() {
  return (
    <Select
      label="Your favorite library"
      placeholder="Pick value"
      data={['React', 'Angular', 'Vue', 'Svelte']}
    />
  );
}

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:

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

function Demo() {
  return (
    <Select
      placeholder="Pick value"
      data={['React', 'Angular', 'Vue', 'Svelte']}
      loading
    />
  );
}

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.

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:

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:

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

function Demo() {
  return (
    <Select
      label="Your favorite library"
      placeholder="Pick value"
      autoSelectOnBlur
      searchable
      data={['React', 'Angular', 'Vue', 'Svelte']}
    />
  );
}

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
import { Select } from '@mantine/core';

function Demo() {
  return (
    <Select
      label="Your favorite library"
      placeholder="Pick value"
      data={['React', 'Angular', 'Vue', 'Svelte']}
      defaultValue="React"
      clearable
    />
  );
}

Clear section mode

The clearSectionMode prop determines how the clear button and rightSection are rendered:

  • 'both' (default) – render both the clear button and rightSection
  • 'rightSection' – render only the user-supplied rightSection, ignore clear button
  • 'clear' – render only the clear button, ignore rightSection
import { CaretDownIcon } from '@phosphor-icons/react';
import { Select, Stack } from '@mantine/core';

function Demo() {
  return (
    <Stack>
      <Select
        label="clearSectionMode='both' (default)"
        placeholder="Pick value"
        data={['React', 'Angular', 'Vue', 'Svelte']}
        defaultValue="React"
        clearable
        rightSection={<CaretDownIcon size={16} />}
        clearSectionMode="both"
      />

      <Select
        label="clearSectionMode='rightSection'"
        placeholder="Pick value"
        data={['React', 'Angular', 'Vue', 'Svelte']}
        defaultValue="React"
        clearable
        rightSection={<CaretDownIcon size={16} />}
        clearSectionMode="rightSection"
      />

      <Select
        label="clearSectionMode='clear'"
        placeholder="Pick value"
        data={['React', 'Angular', 'Vue', 'Svelte']}
        defaultValue="React"
        clearable
        rightSection={<CaretDownIcon size={16} />}
        clearSectionMode="clear"
      />
    </Stack>
  );
}

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:

This is default behavior, click 'React' in the dropdown

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

function Demo() {
  return (
    <>
      <Select
        label="Option can NOT be deselected"
        placeholder="Pick value"
        data={['React', 'Angular', 'Vue', 'Svelte']}
        defaultValue="React"
        allowDeselect={false}
      />

      <Select
        label="Option can be deselected"
        description="This is default behavior, click 'React' in the dropdown"
        placeholder="Pick value"
        data={['React', 'Angular', 'Vue', 'Svelte']}
        defaultValue="React"
        allowDeselect
        mt="md"
      />
    </>
  );
}

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:

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

function Demo() {
  return (
    <>
      <Select
        label="Opens on focus"
        placeholder="Pick value"
        searchable
        openOnFocus
        data={['React', 'Angular', 'Vue', 'Svelte']}
      />
      <Select
        label="Does not open on focus"
        placeholder="Pick value"
        searchable
        openOnFocus={false}
        data={['React', 'Angular', 'Vue', 'Svelte']}
      />
    </>
  );
}

Searchable

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

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

function Demo() {
  return (
    <Select
      label="Your favorite library"
      placeholder="Pick value"
      data={['React', 'Angular', 'Vue', 'Svelte']}
      searchable
    />
  );
}

Controlled search value

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

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.

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

function Demo() {
  return (
    <Select
      label="Your favorite library"
      placeholder="Pick value"
      data={['React', 'Angular', 'Vue', 'Svelte']}
      searchable
      nothingFoundMessage="Nothing found..."
    />
  );
}

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.

Check icon position
import { Select } from '@mantine/core';

function Demo() {
  return (
    <Select
      checkIconPosition="left"
      data={['React', 'Angular', 'Svelte', 'Vue']}
      dropdownOpened
      pb={150}
      label="Control check icon"
      placeholder="Pick value"
      defaultValue="React"
    />
  );
}

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:

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

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

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

Data formats

Select data prop accepts data in one of the following formats:

Array of primitive values (strings, numbers, booleans):

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

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

Array of objects with value, label and optional disabled keys:

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

function Demo() {
  return (
    <Select
      data={[
        { value: 'react', label: 'React' },
        { value: 'ng', label: 'Angular' },
      ]}
    />
  );
}

Array of groups with primitive value (string, number, boolean) options:

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

function Demo() {
  return (
    <Select
      data={[
        { group: 'Frontend', items: ['React', 'Angular'] },
        { group: 'Backend', items: ['Express', 'Django'] },
      ]}
    />
  );
}

Array of groups with object options:

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

function Demo() {
  return (
    <Select
      data={[
        { group: 'Frontend', items: [{ value: 'react', label: 'React' }, { value: 'ng', label: 'Angular' }] },
        { group: 'Backend', items: [{ value: 'express', label: 'Express' }, { value: 'django', label: 'Django' }] },
      ]}
    />
  );
}

Options filtering

By default, Select filters options by checking if the option label contains the input value. You can change this behavior with the filter prop. The filter function receives an object with the following properties as a single argument:
  • options – array of options or options groups, all options are in { value: string; label: string; disabled?: boolean } format
  • search – current search query
  • limit – value of the limit prop passed to Select

Example of a custom filter function that matches options by words instead of letter sequence:

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

const optionsFilter: OptionsFilter = ({ options, search }) => {
  const splittedSearch = search.toLowerCase().trim().split(' ');
  return (options as ComboboxItem[]).filter((option) => {
    const words = option.label.toLowerCase().trim().split(' ');
    return splittedSearch.every((searchWord) => words.some((word) => word.includes(searchWord)));
  });
};

function Demo() {
  return (
    <Select
      label="Your country"
      placeholder="Pick value"
      data={['Great Britain', 'Russian Federation', 'United States']}
      filter={optionsFilter}
      searchable
    />
  );
}

Sort options

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

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

const optionsFilter: OptionsFilter = ({ options, search }) => {
  const filtered = (options as ComboboxItem[]).filter((option) =>
    option.label.toLowerCase().trim().includes(search.toLowerCase().trim())
  );

  filtered.sort((a, b) => a.label.localeCompare(b.label));
  return filtered;
};

function Demo() {
  return (
    <Select
      label="Your favorite library"
      placeholder="Pick value"
      data={['4 – React', '1 – Angular', '3 – Vue', '2 – Svelte']}
      filter={optionsFilter}
      nothingFoundMessage="Nothing found..."
      searchable
    />
  );
}

Fuzzy search with fuse.js

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

import { Select, ComboboxItem, OptionsFilter } from '@mantine/core';
import Fuse from 'fuse.js';

const optionsFilter: OptionsFilter = ({ options, search }) => {
  if (!search.trim()) {
    return options;
  }

  const fuse = new Fuse(options as ComboboxItem[], {
    keys: ['label'],
    threshold: 0.3,
    minMatchCharLength: 1,
  });

  return fuse.search(search).map((result) => result.item);
};

function Demo() {
  return (
    <Select
      label="Your country"
      placeholder="Pick value"
      data={['Great Britain', 'Russian Federation', 'United States']}
      filter={optionsFilter}
      searchable
    />
  );
}

Large data sets

The best strategy for large data sets is to limit the number of options that are rendered at the same time. You can do this with the limit prop. Note that if you use a custom filter function, you need to implement your own logic to limit the number of options in filter.

Example of Select with 100,000 options, 5 options are rendered at the same time:

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

const largeData = Array(100_000)
  .fill(0)
  .map((_, index) => `Option ${index}`);

function Demo() {
  return (
    <Select
      label="100 000 options autocomplete"
      placeholder="Use limit to optimize performance"
      limit={5}
      data={largeData}
      searchable
    />
  );
}

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.

import { TextAlignCenterIcon, TextAlignJustifyIcon, TextAlignLeftIcon, TextAlignRightIcon, CheckIcon } from '@phosphor-icons/react';
import { Group, Select, SelectProps } from '@mantine/core';

const iconProps = {

  color: 'currentColor',
  opacity: 0.6,
  size: 18,
};

const icons: Record<string, React.ReactNode> = {
  left: <TextAlignLeftIcon {...iconProps} />,
  center: <TextAlignCenterIcon {...iconProps} />,
  right: <TextAlignRightIcon {...iconProps} />,
  justify: <TextAlignJustifyIcon {...iconProps} />,
};

const renderSelectOption: SelectProps['renderOption'] = ({ option, checked }) => (
  <Group flex="1" gap="xs">
    {icons[option.value]}
    {option.label}
    {checked && <CheckIcon style={{ marginInlineStart: 'auto' }} {...iconProps} />}
  </Group>
);

function Demo() {
  return (
    <Select
      label="Select with renderOption"
      placeholder="Select text align"
      data={[
        { value: 'left', label: 'Left' },
        { value: 'center', label: 'Center' },
        { value: 'right', label: 'Right' },
        { value: 'justify', label: 'Justify' },
      ]}
      renderOption={renderSelectOption}
    />
  );
}

Scrollable dropdown

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.

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

const data = Array(100)
  .fill(0)
  .map((_, index) => `Option ${index}`);

function Demo() {
  return (
    <>
      <Select
        label="With scroll area (default)"
        placeholder="Pick value"
        data={data}
        maxDropdownHeight={200}
      />

      <Select
        label="With native scroll"
        placeholder="Pick value"
        data={data}
        withScrollArea={false}
        styles={{ dropdown: { maxHeight: 200, overflowY: 'auto' } }}
        mt="md"
      />
    </>
  );
}

Group options

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

function Demo() {
  return (
    <Select
      label="Your favorite library"
      placeholder="Pick value"
      data={[
        { group: 'Frontend', items: ['React', 'Angular'] },
        { group: 'Backend', items: ['Express', 'Django'] },
      ]}
    />
  );
}

Disabled options

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

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

function Demo() {
  return (
    <Select
      label="Your favorite library"
      placeholder="Pick value"
      data={[
        { value: 'react', label: 'React' },
        { value: 'ng', label: 'Angular' },
        { value: 'vue', label: 'Vue', disabled: true },
        { value: 'svelte', label: 'Svelte', disabled: true },
      ]}
    />
  );
}

Combobox props

You can override Combobox props with comboboxProps. This is useful when you need to change some of the props that are not exposed by Select, for example withinPortal:

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

function Demo() {
  return <Select comboboxProps={{ withinPortal: false }} data={[]} />;
}

Change dropdown z-index

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

function Demo() {
  return <Select comboboxProps={{ zIndex: 1000 }} data={[]} />;
}

Inside Popover

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

import { Popover, Button, Select } from '@mantine/core';

function Demo() {
  return (
    <Popover width={300} position="bottom" withArrow shadow="md">
      <Popover.Target>
        <Button>Toggle popover</Button>
      </Popover.Target>
      <Popover.Dropdown>
        <Select
          label="Your favorite library"
          placeholder="Pick value"
          data={['React', 'Angular', 'Vue', 'Svelte']}
          comboboxProps={{ withinPortal: false }}
        />
      </Popover.Dropdown>
    </Popover>
  );
}

Control dropdown opened state

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.

import { Select, Button } from '@mantine/core';
import { useDisclosure } from '@mantine/hooks';

function Demo() {
  const [dropdownOpened, { toggle }] = useDisclosure();
  return (
    <>
      <Button onClick={toggle} mb="md">
        Toggle dropdown
      </Button>

      <Select
        label="Your favorite library"
        placeholder="Pick value"
        data={['React', 'Angular', 'Vue', 'Svelte']}
        dropdownOpened={dropdownOpened}
      />
    </>
  );
}

Dropdown position

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:

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

function Demo() {
  return (
    <Select
      label="Your favorite library"
      placeholder="Pick value"
      data={['React', 'Angular', 'Vue', 'Svelte']}
      comboboxProps={{ position: 'top', middlewares: { flip: false, shift: false } }}
    />
  );
}

Dropdown width

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

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

function Demo() {
  return (
    <Select
      label="Your favorite library"
      placeholder="Pick value"
      data={['React', 'Angular', 'Vue', 'Svelte']}
      comboboxProps={{ width: 200, position: 'bottom-start' }}
    />
  );
}

Dropdown offset

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

import { Select } from '@mantine/core';
import classes from './Demo.module.css';

function Demo() {
  return (
    <Select
      label="Your favorite library"
      placeholder="Pick value"
      data={['React', 'Angular', 'Vue', 'Svelte']}
      classNames={classes}
      comboboxProps={{ position: 'bottom', middlewares: { flip: false, shift: false }, offset: 0 }}
    />
  );
}

Prevent horizontal infinite scrolling

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

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

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

Dropdown animation

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

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

function Demo() {
  return (
    <Select
      label="Your favorite library"
      placeholder="Pick value"
      data={['React', 'Angular', 'Vue', 'Svelte']}
      comboboxProps={{ transitionProps: { transition: 'pop', duration: 200 } }}
    />
  );
}

Dropdown padding

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

function Demo() {
  return (
    <>
      <Select
        label="Zero padding"
        placeholder="Pick value"
        data={['React', 'Angular', 'Vue', 'Svelte']}
        comboboxProps={{ dropdownPadding: 0 }}
      />
      <Select
        mt="md"
        label="10px padding"
        placeholder="Pick value"
        data={['React', 'Angular', 'Vue', 'Svelte']}
        comboboxProps={{ dropdownPadding: 10 }}
      />
    </>
  );
}

Dropdown shadow

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

function Demo() {
  return (
    <Select
      label="Your favorite library"
      placeholder="Pick value"
      data={['React', 'Angular', 'Vue', 'Svelte']}
      comboboxProps={{ shadow: 'md' }}
    />
  );
}

Left and right sections

Select supports leftSection and rightSection props. These sections are rendered with absolute positioning inside the input wrapper. You can use them to display icons, input controls, or any other elements.

You can use the following props to control sections styles and content:

  • rightSection / leftSection – React node to render on the corresponding side of input
  • rightSectionWidth/leftSectionWidth – controls the width of the right section and padding on the corresponding side of the input. By default, it is controlled by the component size prop.
  • rightSectionPointerEvents/leftSectionPointerEvents – controls the pointer-events property of the section. If you want to render a non-interactive element, set it to none to pass clicks through to the input.
import { Select } from '@mantine/core';
import { SquaresFourIcon } from '@phosphor-icons/react';

function Demo() {
  const icon = <SquaresFourIcon size={16} />;
  return (
    <>
      <Select
        data={['React', 'Angular', 'Vue']}
        leftSectionPointerEvents="none"
        leftSection={icon}
        label="Your favorite library"
        placeholder="Your favorite library"
      />
      <Select
        mt="md"
        data={['React', 'Angular', 'Vue']}
        rightSectionPointerEvents="none"
        rightSection={icon}
        label="Your favorite library"
        placeholder="Your favorite library"
      />
    </>
  );
}

Input props

Select component supports Input and Input.Wrapper component features and all input element props. The Select documentation does not include all features supported by the component – see the Input documentation to learn about all available features.

Input description

Variant
Size
Radius
import { Select } from '@mantine/core';

function Demo() {
  return (
    <Select
      label="Input label"
      description="Input description"
      placeholder="Select placeholder"
      data={['React', 'Angular', 'Vue', 'Svelte']}
    />
  );
}

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.

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

function Demo() {
  return (
    <Select
      label="Your favorite library"
      placeholder="Pick value"
      data={['React', 'Angular', 'Vue', 'Svelte']}
      readOnly
    />
  );
}

Disabled

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

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

function Demo() {
  return (
    <Select
      label="Your favorite library"
      placeholder="Pick value"
      data={['React', 'Angular', 'Vue', 'Svelte']}
      disabled
    />
  );
}

Error state

Invalid name

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

function Demo() {
  return (
    <>
      <Select
        label="Boolean error"
        placeholder="Boolean error"
        error
        data={['React', 'Angular', 'Vue', 'Svelte']}
      />
      <Select
        mt="md"
        label="With error message"
        placeholder="With error message"
        error="Invalid name"
        data={['React', 'Angular', 'Vue', 'Svelte']}
      />
    </>
  );
}

Styles API

Select 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.

Description

Component Styles API

Hover over selectors to highlight corresponding elements

/*
 * Hover over selectors to apply outline styles
 *
 */

Get element ref

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

function Demo() {
  const ref = useRef<HTMLInputElement>(null);
  return <Select ref={ref} />;
}

Accessibility

If Select is used without the label prop, it will not be announced properly by screen readers:

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

// Inaccessible input – screen reader will not announce it properly
function Demo() {
  return <Select />;
}

Set aria-label to make the input accessible. In this case the label will not be visible, but screen readers will announce it:

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

// Accessible input – it has aria-label
function Demo() {
  return <Select aria-label="My input" />;
}

If the label prop is set, the input will be accessible and it is not required to set aria-label:

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

// Accessible input – it has associated label element
function Demo() {
  return <Select label="My input" />;
}

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

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

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

PillsInput

TagsInput