Autocomplete

Autocomplete user input with any list of options
Import

Usage

Autocomplete is an input with which you can suggest user to select one of the given values (if you need to force specific values without free input use Select):

<Autocomplete
label="Your favorite framework/library"
placeholder="Pick one"
data={['React', 'Angular', 'Svelte', 'Vue']}
/>

Controlled

import { useState } from 'react';
import { Autocomplete } from '@mantine/core';
function Demo() {
const [value, setValue] = useState('');
return <Autocomplete value={value} onChange={setValue} />;
}

Data prop

Autocomplete support two different data formats:

  1. An array of strings – use when you do not need to customize item component
  2. An array of objects with required value property and any other additional properties
// Data as an array of strings
<Autocomplete data={['React', 'Angular', 'Svelte', 'Vue']} />
// Data as an array of objects:
// Minimal example (same as first example above)
<Autocomplete data={[
{ value: 'React' },
{ value: 'Angular' },
{ value: 'Svelte' },
{ value: 'Vue' },
]} />
// Additional data properties for custom item component (see documentation below)
<Autocomplete
itemComponent={({ value, color, email, name }) => /* Your custom item component with data properties */}
data={[
{ value: 'bob@handsome.inc', color: 'red', email: 'bob@handsome.inc', name: 'Bob Handsome' },
{ value: 'bill@outlook.com', color: 'teal', email: 'bill@outlook.com', name: 'Bill Gates' },
{ value: 'amy@wong.cn', color: 'blue', email: 'amy@wong.cn', name: 'Amy Wong' },
]}
/>

Dynamic data

data prop can have dynamic values:

function Demo() {
const [value, setValue] = useState('');
const data =
value.trim().length > 0 && !value.includes('@')
? ['gmail.com', 'outlook.com', 'yahoo.com'].map((provider) => `${value}@${provider}`)
: [];
return (
<Autocomplete
value={value}
onChange={setValue}
label="Email"
placeholder="Start typing to see options"
data={data}
/>
);
}

Custom item component

You can change autocomplete 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

data prop must be an array of objects with required value field:

[
{ value: 'bob@handsome.inc', color: 'red', email: 'bob@handsome.inc', name: 'Bob Handsome' },
{ value: 'bill@outlook.com', color: 'teal', email: 'bill@outlook.com', name: 'Bill Gates' },
{ value: 'amy@wong.cn', color: 'blue', email: 'amy@wong.cn', name: 'Amy Wong' },
];

Based on this data shape you can create custom filter function and itemComponent:

import { Group, Avatar, Text, Autocomplete } from '@mantine/core';
export const LABELS_DATA = [
{
image: 'avatar.png',
value: 'Bender Bending Rodríguez',
description: 'Fascinated with cooking, though has no sense of taste',
},
{
image: 'avatar.png',
value: 'Carol Miller',
description: 'One of the richest people on Earth',
},
// ... other items
]
const AutoCompleteItem = forwardRef<HTMLDivElement, ItemProps>(
({ description, value, image, ...others }: ItemProps, ref) => (
<div ref={ref} {...others}>
<Group noWrap>
<Avatar src={image} />
<div>
<Text>{value}</Text>
<Text size="xs" color="dimmed">
{description}
</Text>
</div>
</Group>
</div>
)
);
function Demo() {
return (
<Autocomplete
label="Choose employee of the month"
placeholder="Pick one"
itemComponent={AutoCompleteItem}
data={data}
filter={(value, item) =>
item.value.toLowerCase().includes(value.toLowerCase().trim()) ||
item.description.toLowerCase().includes(value.toLowerCase().trim())
}
/>
);
}

Limit amount of options

By default Autocomplete will render 5 items at a time, to change that set limit prop:

<Autocomplete
label="Only 2 options at a time"
placeholder="Your favorite framework"
limit={2}
data={['React', 'Angular', 'Svelte', 'Vue']}
/>

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
<Autocomplete
transition="pop-top-left"
transitionDuration={80}
transitionTimingFunction="ease"
/>

With icon

You can use any React node as in icon:

<Autocomplete icon={<FrameIcon />} />

Invalid state and error

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

Disabled state

<Autocomplete disabled />

Input props

Component supports all props from Input and InputWrapper components:

Radius
Size
<Autocomplete
placeholder="Pick one"
label="Your favorite framework/library"
required
data={['React', 'Angular', 'Svelte', 'Vue']}
/>

Get input ref

You can get input ref with ref prop:

import { useRef } from 'react';
import { Autocomplete } from '@mantine/core';
function Demo() {
const ref = useRef(null);
return <Autocomplete ref={ref} />;
}

Accessibility

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

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

TypeScript

AutocompleteProps type

Import component props type:

import type { AutocompleteProps } from '@mantine/core';

AutocompleteProps extends React.ComponentPropsWithoutRef<'input'>, all other props are available under Component props tab.

AutocompleteItem type

AutocompleteItem type lets you validate object items that will be passed to Autocomplete data prop:

import type { AutocompleteItem } from '@mantine/core';
const autocompleteData: AutocompleteItem[] = [
{ value: 'John' },
{ value: 'Jake' },
{ value: 'Amy' },
];

AutocompleteStylesNames type

AutocompleteStylesNames type is a union with Autocomplete Styles API names:

import type { AutocompleteStylesNames } from '@mantine/core';
const autocompleteClasses: Partial<Record<AutocompleteStylesNames, 'string'>> = {
dropdown: 'autocomplete-dropdown',
input: 'autocomplete-input',
};
<Autocomplete classNames={autocompleteClasses} />;

See full styles descriptions list under Styles API tab.

Build fully functional accessible web applications faster than ever
Feedback
Your feedback is most valuable contribution to the project, please share how you use Mantine, what features are missing and what is done good
Leave feedback