K

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 component):

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

Controlled

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

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: `${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:

// Minimum data for default autocomplete used in previous examples
[{ value: 'React' }, { value: 'Angular' }, { value: 'Svelte' }, { value: 'Vue' }];

You can add any other fields to your 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' },
];

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

import { Group, Avatar, Text, UnstyledButton, Autocomplete } from '@mantine/core';
const 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' },
];
function AutoCompleteItem({ color, email, name, ...others }) {
return (
<UnstyledButton {...others}>
<Group>
<Avatar color={color}>
{name
.split(' ')
.map((part) => part.charAt(0).toUpperCase())
.join('')}
</Avatar>
<div>
<Text>{name}</Text>
<Text size="xs" color="blue">
{email}
</Text>
</div>
</Group>
</UnstyledButton>
);
}
function Demo() {
return (
<Autocomplete
label="Choose employee of the month"
placeholder="Pick one"
itemComponent={AutoCompleteItem}
data={data}
filter={(value, item) =>
item.name.toLowerCase().includes(value.toLowerCase().trim()) ||
item.email.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={[{ value: 'React' }, { value: 'Angular' }, { value: 'Svelte' }, { value: 'Vue' }]}
/>

Input props

Component supports all props from Input and InputWrapper components:

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

Get element ref

You can get input ref with elementRef prop:

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

Server side rendering

Component uses use-id hook to generate unique ids and aria- attributes, provide static id prop to prevent props mismatch:

<Autocomplete /> // -> random id generated both on client and server, props mismatch warning
<Autocomplete id="my-accordion" /> // -> id is static, no mismatches

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
Build fully functional accessible web applications with ease
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