group | package | title | order | slug | category | description | props | import | source | docs | styles | ||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
mantine-core |
@mantine/core |
Select |
1 |
/core/select/ |
inputs |
Custom searchable select |
|
import { Select } from '@mantine/core'; |
mantine-core/src/Select/Select.tsx |
core/Select.mdx |
|
import { SelectDemos } from '@mantine/demos';
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:
<Demo data={SelectDemos.itemComponent} demoProps={{ toggle: true, zIndex: 4 }} />
Bare minimum usage example:
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" />
Select support two different data formats:
- An array of strings – use when you do not need to customize item component or display
label
different thanvalue
. - An array of objects with required
value
andlabel
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',
},
]}
/>
Set searchable
prop to enable search in select and nothingFound
prop to provide label that will be shown when no options were found:
Set searchValue
and onSearchChange
prop to enable controlled search in select:
Set clearable
prop to enable clearing select value.
When prop is true and value is selected clear button will replace chevron in right section:
To allow items deselection set allowDeselect
, user will also be able to deselect item if clearable
prop is set:
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:
When dropdown height is exceeded dropdown becomes scrollable, to change max-height set maxDropdownHeight
prop with value in px:
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 consumedata
objects
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:
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 optionstransitionDuration
– transition duration in ms, defaults to 0transitionTimingFunction
– defaults totheme.transitionTimingFunction
By default, Select uses ScrollArea to render dropdown.
If you want to use native scrollbars instead, set div
as a dropdown component:
Use data-selected
and data-hovered
attributes to add styles to items depending on their state:
<Demo data={SelectDemos.icon} demoProps={{ zIndex: 4 }} />
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 { useRef } from 'react';
import { Select } from '@mantine/core';
function Demo() {
const ref = useRef<HTMLInputElement>(null);
return <Select ref={ref} data={[]} />;
}
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" />