v2.5.1
Discord
Source code

Autocomplete

Autocomplete user input with any list of options
Import
Source
View source code
Docs
Edit this page
Package
@mantine/core

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';


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 (
    <div {...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>
    </div>
  );
}


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={['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={<HashIcon />} />

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 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-autocomplete" /> // -> 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
Project
Contribute to MantineChangelogReleases
Community
Join Discord communityFollow on TwitterEmail newsletterGithub discussions
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
Built by Vitaly Rtishchev and these awesome people
Join Discord community
Follow Mantine on Twitter