Welcome to Mantine, React components library that you always wished for
Welcome to Mantine, React components library that you always wished for

MultiSelect

Custom searchable multi select

Import

Source

View source code

Docs

Edit this page

Package

@mantine/core

Made with Combobox

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

Usage

MultiSelect provides a way to enter multiple values. MultiSelect is similar to TagsInput, but it does not allow entering custom values.

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

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

Controlled

MultiSelect value must be an array of strings, other types are not supported. onChange function is called with an array of strings as a single argument.

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

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

Searchable

Set searchable prop to allow filtering options by user input:

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

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

Nothing found

Set nothingFoundMessage prop to display given message when no options match search query. If nothingFoundMessage is not set, MultiSelect dropdown will be hidden when no options match search query. The message is not displayed when trimmed search query is empty.

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

function Demo() {
  return (
    <MultiSelect
      label="Your favorite libraries"
      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}.

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

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

Max selected values

You can limit the number of selected values with maxValues prop. This will not allow adding more values once the limit is reached.

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

function Demo() {
  return (
    <MultiSelect
      label="Your favorite libraries"
      placeholder="Select up to 2 libraries"
      data={['React', 'Angular', 'Vue', 'Svelte']}
      maxValues={2}
    />
  );
}

Hide selected options

To remove selected options from the list of available options, set hidePickedOptions prop:

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

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

Data formats

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

Array of strings:

import { MultiSelect } from '@mantine/core';
function Demo() {
  return <MultiSelect data={['React', 'Angular']} />;
}

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

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

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

Array of groups with string options:

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

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

Array of groups with object options:

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

function Demo() {
  return (
    <MultiSelect
      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, MultiSelect filters options by checking if the option label contains input value. You can change this behavior with filter prop.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 limit prop passed to MultiSelect

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

import { MultiSelect, 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 (
    <MultiSelect
      label="What countries have you visited?"
      placeholder="Pick values"
      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 filter function:

import { MultiSelect, 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 (
    <MultiSelect
      label="Your favorite libraries"
      placeholder="Pick values"
      data={['4 – React', '1 – Angular', '3 – Vue', '2 – Svelte']}
      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 it with 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 MultiSelect with 100 000 options, 5 options are rendered at the same time:

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

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

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

Scrollable dropdown

By default, the options list is wrapped with ScrollArea.Autosize. You can control dropdown max-height with 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 dropdown styles with Styles API.

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

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

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

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

Group options

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

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

Disabled options

When option is disabled, it cannot be selected and is ignored in keyboard navigation. Note that user can still enter disabled option as a value. If you want to prohibit certain values, use controlled component and filter them out in onChange function.

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

function Demo() {
  return (
    <MultiSelect
      label="Your favorite libraries"
      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. It is useful when you need to change some of the props that are not exposed by MultiSelect, for example withinPortal:

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

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

Input props

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

Input description

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

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

Read only

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

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

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

Disabled

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

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

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

Error state

Invalid name

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

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

Styles API

MultiSelect supports Styles API, you can add styles to any inner element of the component withclassNames prop. Follow Styles API documentation to learn more.

Description

ReactAngular

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

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

Accessibility

If MultiSelect is used without label prop, it will not be announced properly by screen reader:

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

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

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

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

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

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

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

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

Previous

Combobox

Next

Pill

Welcome to Mantine, React components library that you always wished for

Build fully functional accessible web applications faster than ever

About

ContributeAbout MantineChangelogReleases

Community

Chat on DiscordFollow on TwitterFollow on GithubGitHub discussions

Project

Mantine UIDocumentationGithub organizationnpm organization

Built by Vitaly Rtishchev and these awesome people

Join Discord communityFollow Mantine on Twitter