Select

Custom searchable select
Import
Source
View source code
Docs
Edit this page
Package
@mantine/core

Usage

Select component allows user to pick one option from the given data, use this component when you need to create custom value selection which is not possible with NativeSelect:

Bare minimum usage example:

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


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

Controlled

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


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

Note that Select value should always be either string or null:

// Incorrect, will have bugs
<Select data={[{ value: 1, label: '1' }]} value={1} />


// Correct, works as expected
<Select data={[{ value: '1', label: '1' }]} value="1" />

Data prop

Select support two different data formats:

  1. An array of strings – use when you do not need to customize item component or display label different than value.
  2. An array of objects with required value and label properties and any other additional properties.
// Data as an array of strings, will be mapped to
// [
//  { value: 'React', label: 'React' },
//  { value: 'Angular', label: 'Angular' },
//  { value: 'Svelte', label: 'Svelte' },
//  { value: 'Vue', label: 'Vue' },
// ]
<Select data={['React', 'Angular', 'Svelte', 'Vue']} />


// Data as an array of objects:
// Minimal example (same as first example above)
<Select data={[
  { value: 'React', label: 'React' },
  { value: 'Angular', label: 'Angular' },
  { value: 'Svelte', label: 'Svelte' },
  { value: 'Vue', label: 'Vue' },
]} />


// Additional data properties for custom item component (see documentation below)
<Select
  itemComponent={({ value, label, image, name }) => /* Your custom item component with data properties */}
  data={[
    {
      value: 'bob@handsome.inc',
      label: 'bob@handsome.inc',
      image: 'image-link',
      name: 'Bob Handsome',
    },
    {
      value: 'bill@outlook.com',
      label: 'bill@outlook.com',
      image: 'image-link',
      name: 'Bill Rataconda',
    },
    {
      value: 'amy@wong.cn',
      label: 'amy@wong.cn',
      image: 'image-link',
      name: 'Amy Wong',
    },
  ]}
/>

Searchable

Set searchable prop to enable search in select and nothingFound prop to provide label that will be shown when no options were found:

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


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

Controlled search

Set searchValue and onSearchChange prop to enable controlled search in select:

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


function Demo() {
  const [searchValue, onSearchChange] = useState('');


  return (
    <Select
      label="Your favorite framework/library"
      placeholder="Pick one"
      searchable
      onSearchChange={onSearchChange}
      searchValue={searchValue}
      nothingFound="No options"
      data={['React', 'Angular', 'Svelte', 'Vue']}
    />
  );
}

Clearable

Set clearable prop to enable clearing select value. When prop is true and value is selected clear button will replace chevron in right section:

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


function Demo() {
  return (
    <>
      <Select clearable />
      <Select searchable clearable />
    </>
  );
}

Allow deselect items

To allow items deselection set allowDeselect, user will also be able to deselect item if clearable prop is set:

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


function Demo() {
  return <Select allowDeselect />;
}

Creatable

Set creatable and getCreateLabel props to enable creating new select item. Note that you will need to handle data state to manage item creation correctly:

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


export function Demo() {
  const [data, setData] = useState([
    { value: 'react', label: 'React' },
    { value: 'ng', label: 'Angular' },
  ]);


  return (
    <Select
      label="Creatable Select"
      data={data}
      placeholder="Select items"
      nothingFound="Nothing found"
      searchable
      creatable
      getCreateLabel={(query) => `+ Create ${query}`}
      onCreate={(query) => {
        const item = { value: query, label: query };
        setData((current) => [...current, item]);
        return item;
      }}
    />
  );
}

Grouping items

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


function Demo() {
  return (
    <Select
      label="Your favorite Rick and Morty character"
      placeholder="Pick one"
      data={[
        { value: 'rick', label: 'Rick', group: 'Used to be a pickle' },
        { value: 'morty', label: 'Morty', group: 'Never was a pickle' },
        { value: 'beth', label: 'Beth', group: 'Never was a pickle' },
        { value: 'summer', label: 'Summer', group: 'Never was a pickle' },
      ]}
    />
  );
}

Disable items

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


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

Large data set

When dropdown height is exceeded dropdown becomes scrollable, to change max-height set maxDropdownHeight prop with value in px:

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


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


function Demo() {
  return (
    <Select
      label="What item is the best?"
      placeholder="Pick one"
      searchable
      nothingFound="No options"
      maxDropdownHeight={280}
      data={data}
    />
  );
}

Custom item component

You can change select item component and filtering logic that is used in search. To do so you will need to:

  • Add extra props to data objects
  • Create filter function which determines whether item should be added to the search results
  • Provide itemComponent which will consume data objects
import { forwardRef } from 'react';
import { Group, Avatar, Text, Select } from '@mantine/core';


const data = [
  {
    image: 'https://img.icons8.com/clouds/256/000000/futurama-bender.png',
    label: 'Bender Bending Rodríguez',
    value: 'Bender Bending Rodríguez',
    description: 'Fascinated with cooking',
  },


  {
    image: 'https://img.icons8.com/clouds/256/000000/futurama-mom.png',
    label: 'Carol Miller',
    value: 'Carol Miller',
    description: 'One of the richest people on Earth',
  },
  {
    image: 'https://img.icons8.com/clouds/256/000000/homer-simpson.png',
    label: 'Homer Simpson',
    value: 'Homer Simpson',
    description: 'Overweight, lazy, and often ignorant',
  },
  {
    image: 'https://img.icons8.com/clouds/256/000000/spongebob-squarepants.png',
    label: 'Spongebob Squarepants',
    value: 'Spongebob Squarepants',
    description: 'Not just a sponge',
  },
];


interface ItemProps extends React.ComponentPropsWithoutRef<'div'> {
  image: string;
  label: string;
  description: string;
}


const SelectItem = forwardRef<HTMLDivElement, ItemProps>(
  ({ image, label, description, ...others }: ItemProps, ref) => (
    <div ref={ref} {...others}>
      <Group noWrap>
        <Avatar src={image} />


        <div>
          <Text size="sm">{label}</Text>
          <Text size="xs" opacity={0.65}>
            {description}
          </Text>
        </div>
      </Group>
    </div>
  )
);


function Demo() {
  return (
    <Select
      label="Choose employee of the month"
      placeholder="Pick one"
      itemComponent={SelectItem}
      data={data}
      searchable
      maxDropdownHeight={400}
      nothingFound="Nobody here"
      filter={(value, item) =>
        item.label.toLowerCase().includes(value.toLowerCase().trim()) ||
        item.description.toLowerCase().includes(value.toLowerCase().trim())
      }
    />
  );
}

Dropdown position

By default, dropdown is placed below the input and when there is not enough space, it flips to be above the input. To change this behavior, set dropdownPosition prop:

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


function Demo() {
  return <Select />;
}

Animations

By default, dropdown animations are turned off to increase responsiveness. You can enable them by setting optional props:

  • transition – premade transition name or custom transition styles object, see Transition component for all available options
  • transitionDuration – transition duration in ms, defaults to 0
  • transitionTimingFunction – defaults to theme.transitionTimingFunction
import { Select } from '@mantine/core';


function Demo() {
  return (
    <Select
      transition="pop-top-left"
      transitionDuration={80}
      transitionTimingFunction="ease"
    />
  );
}

Native scrollbars

By default, Select uses ScrollArea to render dropdown. If you want to use native scrollbars instead, set div as a dropdown component:

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


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


function Demo() {
  return (
    <Select
      data={data}
      label="Select with native scrollbars"
      placeholder="Dropdown with native scrollbars"
      dropdownComponent="div"
    />
  );
}

Styles API

Use data-selected and data-hovered attributes to add styles to items depending on their state:

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


function Demo() {
  return (
    <Select
      placeholder="Custom active styles"
      label="Custom active styles"
      defaultValue="Vue"
      data={['React', 'Angular', 'Vue', 'Svelte']}
      styles={(theme) => ({
        item: {
          // applies styles to selected item
          '&[data-selected]': {
            '&, &:hover': {
              backgroundColor:
                theme.colorScheme === 'dark' ? theme.colors.teal[9] : theme.colors.teal[1],
              color: theme.colorScheme === 'dark' ? theme.white : theme.colors.teal[9],
            },
          },


          // applies styles to hovered item (with mouse or keyboard)
          '&[data-hovered]': {},
        },
      })}
    />
  );
}

With icon

import { Select } from '@mantine/core';
import { IconHash } from '@tabler/icons';


function Demo() {
  return (
    <Select
      label="Pick a hashtag"
      placeholder="Pick a hashtag"
      data={['React', 'Angular', 'Svelte', 'Vue']}
      icon={<IconHash size={14} />}
    />
  );
}

Invalid state and error

Pick at least one item
// Error as boolean – red border color
<Select error />


// Error as React node – red border color and message below input
<Select error="Pick at least one item" />

Disabled state

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


function Demo() {
  return <Select disabled />;
}

Read only

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


function Demo() {
  return (
    <Select
      label="Read only select"
      placeholder="Pick one"
      defaultValue="react"
      readOnly
      data={[
        { value: 'react', label: 'React' },
        { value: 'ng', label: 'Angular' },
        { value: 'svelte', label: 'Svelte' },
        { value: 'vue', label: 'Vue' },
      ]}
    />
  );
}

Right section

You can replace icon in right section with rightSection prop. Note that in this case clearable option will not work and will need to handle it yourself:

import { Select } from '@mantine/core';
import { IconChevronDown } from '@tabler/icons';


function Demo() {
  return (
    <Select
      label="Your favorite framework/library"
      placeholder="Pick one"
      rightSection={<IconChevronDown size={14} />}
      rightSectionWidth={30}
      styles={{ rightSection: { pointerEvents: 'none' } }}
      data={['React', 'Angular', 'Svelte', 'Vue']}
    />
  );
}

Input props

Radius
xs
sm
md
lg
xl
Size
xs
sm
md
lg
xl
import { Select } from '@mantine/core';


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

Get input element ref

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


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

Accessibility

Provide aria-label in case you use component without label for screen reader support:

<Select /> // -> not ok, select is not labeled
<Select label="My select" /> // -> ok, select and label is connected
<Select aria-label="My select" /> // -> ok, label is not visible but will be announced by screen reader

If you use clearable option set clearButtonLabel:

<Select clearable clearButtonLabel="Clear select field" />
Go back
SegmentedControl – @mantine/core
Up next
Slider – @mantine/core

Select component props

NameTypeDescription
allowDeselect
boolean
Allow deselecting items on click
clearButtonLabel
string
aria-label for clear button
clearButtonTabIndex
0 | -1
Set the clear button tab index to disabled or default after input field
clearable
boolean
Allow to clear item
creatable
boolean
Allow creatable option
data *
readonly (string | SelectItem)[]
Select data used to render items in dropdown
defaultValue
string
Uncontrolled input defaultValue
description
ReactNode
Input description, displayed after label
descriptionProps
Record<string, any>
Props spread to description element
disabled
boolean
Disabled input state
dropdownComponent
any
Change dropdown component, can be used to add native scrollbars
dropdownPosition
"bottom" | "top" | "flip"
Dropdown positioning behavior
error
ReactNode
Displays error message after input
errorProps
Record<string, any>
Props spread to error element
filter
(value: string, item: SelectItem) => boolean
Function based on which items in dropdown are filtered
filterDataOnExactSearchMatch
boolean
Should data be filtered when search value exactly matches selected item
getCreateLabel
(query: string) => ReactNode
Function to get create Label
hoverOnSearchChange
boolean
Hovers the first result when search query changes
icon
ReactNode
Adds icon on the left side of input
iconWidth
Width<string | number>
Width of icon section in px
initiallyOpened
boolean
Initial dropdown opened state
inputContainer
(children: ReactNode) => ReactNode
Input container component, defaults to React.Fragment
inputWrapperOrder
("input" | "label" | "error" | "description")[]
Controls order of the Input.Wrapper elements
itemComponent
FC<any>
Change item renderer
label
ReactNode
Input label, displayed before input
labelProps
Record<string, any>
Props spread to label element
limit
number
Limit amount of items displayed at a time for searchable select
maxDropdownHeight
number
Maximum dropdown height in px
nothingFound
ReactNode
Nothing found label
onChange
(value: string) => void
Controlled input onChange handler
onCreate
(query: string) => string | SelectItem
Called when create option is selected
onDropdownClose
() => void
Called when dropdown is closed
onDropdownOpen
() => void
Called when dropdown is opened
onSearchChange
(query: string) => void
Called each time search value changes
positionDependencies
any[]
useEffect dependencies to force update dropdown position
radius
number | "xs" | "sm" | "md" | "lg" | "xl"
Input border-radius from theme or number to set border-radius in px
required
boolean
Adds required attribute to the input and red asterisk on the right side of label Sets required on input element
rightSection
ReactNode
Right section of input, similar to icon but on the right
rightSectionProps
Record<string, any>
Props spread to rightSection div element
rightSectionWidth
Width<string | number>
Width of right section, is used to calculate input padding-right
searchValue
string
Controlled search input value
searchable
boolean
Set to true to enable search
selectOnBlur
boolean
Select highlighted item on blur
shadow
MantineShadow
Dropdown shadow from theme or any value to set box-shadow
shouldCreate
(query: string, data: SelectItem[]) => boolean
Function to determine if create label should be displayed
size
"xs" | "sm" | "md" | "lg" | "xl"
Input size
switchDirectionOnFlip
boolean
Whether to switch item order and keyboard navigation on dropdown position flip
transition
MantineTransition
Dropdown body appear/disappear transition
transitionDuration
number
Dropdown body transition duration
transitionTimingFunction
string
Dropdown body transition timing function, defaults to theme.transitionTimingFunction
value
string
Controlled input value
variant
"unstyled" | "default" | "filled"
Defines input appearance, defaults to default in light color scheme and filled in dark
withAsterisk
boolean
Determines whether required asterisk should be rendered, overrides required prop, does not add required attribute to the input
withinPortal
boolean
Whether to render the dropdown in a Portal
wrapperProps
Record<string, any>
Properties spread to root element
zIndex
ZIndex
Dropdown z-index

Select component Styles API

NameStatic selectorDescription
dropdown.mantine-Select-dropdownDropdown element
item.mantine-Select-itemItem element, rendered inside dropdown
nothingFound.mantine-Select-nothingFoundNothing found label
separator.mantine-Select-separatorDivider wrapper
separatorLabel.mantine-Select-separatorLabelSeparator Label
itemsWrapper.mantine-Select-itemsWrapperWraps all items in dropdown
wrapper.mantine-Select-wrapperRoot Input element
invalid.mantine-Select-invalidInvalid input modifier
disabled.mantine-Select-disabledInvalid disabled modifier
icon.mantine-Select-iconInput icon wrapper on the left side of the input, controlled by icon prop
withIcon.mantine-Select-withIconInput element styles when used with icon, controlled by icon prop
input.mantine-Select-inputMain input element
rightSection.mantine-Select-rightSectionInput right section, controlled by rightSection prop
root.mantine-Select-rootRoot element
label.mantine-Select-labelLabel element styles, defined by label prop
error.mantine-Select-errorError element styles, defined by error prop
description.mantine-Select-descriptionDescription element styles, defined by description prop
required.mantine-Select-requiredRequired asterisk element styles, defined by required prop
Learn more about Styles API
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 community
Follow Mantine on Twitter