Autocomplete

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

Usage

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


function Demo() {
  return (
    <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={[]} />;
}

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
import { Autocomplete } from '@mantine/core';


function Demo() {
  return (
    <>
      {/* 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
        // Your custom item component with data properties
        itemComponent={({ value, color, email, name }) => <div />}
        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

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}
    />
  );
}

Group options

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


function Demo() {
  return (
    <Autocomplete
      label="Your favorite Rick and Morty character"
      placeholder="Pick one"
      data={[
        { value: 'Rick', group: 'Used to be a pickle' },
        { value: 'Morty', group: 'Never was a pickle' },
        { value: 'Beth', group: 'Never was a pickle' },
        { value: 'Summer', group: 'Never was a pickle' },
      ]}
    />
  );
}

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
import { forwardRef } from 'react';
import { Group, Avatar, Text, MantineColor, SelectItemProps, Autocomplete } from '@mantine/core';


const charactersList = [
  {
    image: 'https://img.icons8.com/clouds/256/000000/futurama-bender.png',
    label: 'Bender Bending Rodríguez',
    description: 'Fascinated with cooking, though has no sense of taste',
  },


  {
    image: 'https://img.icons8.com/clouds/256/000000/futurama-mom.png',
    label: 'Carol Miller',
    description: 'One of the richest people on Earth',
  },
  {
    image: 'https://img.icons8.com/clouds/256/000000/homer-simpson.png',
    label: 'Homer Simpson',
    description: 'Overweight, lazy, and often ignorant',
  },
  {
    image: 'https://img.icons8.com/clouds/256/000000/spongebob-squarepants.png',
    label: 'Spongebob Squarepants',
    description: 'Not just a sponge',
  },
];


const data = charactersList.map((item) => ({ ...item, value: item.label }));


interface ItemProps extends SelectItemProps {
  color: MantineColor;
  description: string;
  image: string;
}


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:

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


function Demo() {
  return (
    <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
import { Autocomplete } from '@mantine/core';


function Demo() {
  return <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
import { Autocomplete } from '@mantine/core';


function Demo() {
  return (
    <Autocomplete
      data={['React', 'Angular', 'Svelte', 'Vue']}
      transition="pop-top-left"
      transitionDuration={80}
      transitionTimingFunction="ease"
    />
  );
}

With icon

import { Autocomplete } from '@mantine/core';
import { IconHash } from '@tabler/icons';


function Demo() {
  return <Autocomplete icon={<IconHash />} data={['React', 'Angular', 'Svelte', 'Vue']} />;
}

Invalid state and error

Field is required
import { Autocomplete } from '@mantine/core';


function Demo() {
  return (
    <>
      {/* Error as boolean – red border color */}
      <Autocomplete error data={['React', 'Angular', 'Svelte', 'Vue']} />


      {/* Error as React node – red border color and message below input */}
      <Autocomplete error="Field is required" data={['React', 'Angular', 'Svelte', 'Vue']} />
    </>
  );
}

Disabled state

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


function Demo() {
  return <Autocomplete disabled data={['React', 'Angular', 'Svelte', 'Vue']} />;
}

Input props

Radius
xs
sm
md
lg
xl
Size
xs
sm
md
lg
xl
import { Autocomplete } from '@mantine/core';


function Demo() {
  return (
    <Autocomplete
      placeholder="Pick one"
      label="Your favorite framework/library"
      withAsterisk
      data={['React', 'Angular', 'Svelte', 'Vue']}
    />
  );
}

Get input ref

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


function Demo() {
  const ref = useRef<HTMLInputElement>(null);
  return <Autocomplete ref={ref} data={[]} />;
}

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
UnstyledButton – @mantine/core
Up next
Checkbox – @mantine/core

Autocomplete component props

NameTypeDescription
data *
readonly (string | AutocompleteItem)[]
Select data used to render items in dropdown
defaultValue
string
Uncontrolled input defaultValue
description
ReactNode
Input description, displayed after label
descriptionProps
Record<string, any>
Props spread to description element
disabled
boolean
Disabled input state
dropdownComponent
any
Change dropdown component, can be used to add native scrollbars
dropdownPosition
"bottom" | "top" | "flip"
Dropdown positioning behavior
error
ReactNode
Displays error message after input
errorProps
Record<string, any>
Props spread to error element
filter
(value: string, item: AutocompleteItem) => boolean
Function based on which items in dropdown are filtered
hoverOnSearchChange
boolean
Hovers the first result when input changes
icon
ReactNode
Adds icon on the left side of input
iconWidth
Width<string | number>
Width of icon section in px
initiallyOpened
boolean
Initial dropdown opened state
inputContainer
(children: ReactNode) => ReactNode
Input container component, defaults to React.Fragment
inputWrapperOrder
("input" | "label" | "error" | "description")[]
Controls order of the Input.Wrapper elements
itemComponent
FC<any>
Change item renderer
label
ReactNode
Input label, displayed before input
labelProps
Record<string, any>
Props spread to label element
limit
number
Limit amount of items displayed at a time for searchable select
maxDropdownHeight
string | number
Maximum dropdown height
nothingFound
ReactNode
Nothing found label
onChange
(value: string) => void
Controlled input onChange handler
onDropdownClose
() => void
Called when dropdown is closed
onDropdownOpen
() => void
Called when dropdown is opened
onItemSubmit
(item: AutocompleteItem) => void
Called when item from dropdown was selected
positionDependencies
any[]
useEffect dependencies to force update dropdown position
radius
number | "xs" | "sm" | "md" | "lg" | "xl"
Input border-radius from theme or number to set border-radius in px
required
boolean
Sets required on input element
rightSection
ReactNode
Right section of input, similar to icon but on the right
rightSectionProps
Record<string, any>
Props spread to rightSection div element
rightSectionWidth
Width<string | number>
Width of right section, is used to calculate input padding-right
shadow
MantineShadow
Dropdown shadow from theme or any value to set box-shadow
size
"xs" | "sm" | "md" | "lg" | "xl"
Input size
switchDirectionOnFlip
boolean
Whether to switch item order and keyboard navigation on dropdown position flip
transition
MantineTransition
Dropdown body appear/disappear transition
transitionDuration
number
Dropdown body transition duration
transitionTimingFunction
string
Dropdown body transition timing function, defaults to theme.transitionTimingFunction
value
string
Controlled input value
variant
"unstyled" | "default" | "filled"
Defines input appearance, defaults to default in light color scheme and filled in dark
withAsterisk
boolean
Determines whether required asterisk should be rendered, overrides required prop, does not add required attribute to the input
withinPortal
boolean
Whether to render the dropdown in a Portal
wrapperProps
Record<string, any>
Properties spread to root element
zIndex
ZIndex
Dropdown z-index

Autocomplete component Styles API

NameStatic selectorDescription
dropdown.mantine-Autocomplete-dropdownDropdown element
item.mantine-Autocomplete-itemItem element, rendered inside dropdown
nothingFound.mantine-Autocomplete-nothingFoundNothing found label
separator.mantine-Autocomplete-separatorDivider wrapper
separatorLabel.mantine-Autocomplete-separatorLabelSeparator Label
itemsWrapper.mantine-Autocomplete-itemsWrapperWraps all items in dropdown
wrapper.mantine-Autocomplete-wrapperRoot Input element
invalid.mantine-Autocomplete-invalidInvalid input modifier
disabled.mantine-Autocomplete-disabledInvalid disabled modifier
icon.mantine-Autocomplete-iconInput icon wrapper on the left side of the input, controlled by icon prop
withIcon.mantine-Autocomplete-withIconInput element styles when used with icon, controlled by icon prop
input.mantine-Autocomplete-inputMain input element
rightSection.mantine-Autocomplete-rightSectionInput right section, controlled by rightSection prop
root.mantine-Autocomplete-rootRoot element
label.mantine-Autocomplete-labelLabel element styles, defined by label prop
error.mantine-Autocomplete-errorError element styles, defined by error prop
description.mantine-Autocomplete-descriptionDescription element styles, defined by description prop
required.mantine-Autocomplete-requiredRequired asterisk element styles, defined by required prop
Learn more about Styles API
Build fully functional accessible web applications faster than ever
About
ContributeAbout MantineChangelogReleases
Community
Chat on DiscordFollow on TwitterFollow on GithubGitHub discussions
Project
Mantine UIDocumentationGithub organizationnpm organization
Built by Vitaly Rtishchev and these awesome people
Join Discord community
Follow Mantine on Twitter