v3.6.14
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
  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
  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:

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


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

Autocomplete item component and filtering logic can be changed. To do so:

  • 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' },
];

Then define custom filter function and itemComponent which will consume data:

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']}
/>

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
<Autocomplete  />

Animations

By default, dropdown animations are turned off to increase responsiveness. To enable animations set the following 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

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

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
xs
sm
md
lg
xl
Size
xs
sm
md
lg
xl
<Autocomplete
  placeholder="Pick one"
  label="Your favorite framework/library"
  required
  data={['React', 'Angular', 'Svelte', 'Vue']}
/>

Get input ref

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 component does not have a label for screen reader support:

<Autocomplete /> // -> not ok, input is not labeled
<Autocomplete label="My input" /> // -> ok, input and label is connected
<Autocomplete aria-label="My input" /> // -> ok, label is not visible but will be announced by screen reader
Go back
ActionIcon – @mantine/core
Up next
Button – @mantine/core
Build fully functional accessible web applications faster than ever
Project
Contribute to MantineMedia assetsChangelogReleases
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