Autocomplete

Autocomplete user input with any list of options

Source

View source code

LLM docs

LLM documentation

Docs

Edit this page

PackageIcon

@mantine/core

Made with Combobox

Autocomplete is an opinionated component built on top of the Combobox component. It has a limited set of features to cover only basic use cases. If you need more advanced features, you can build your own component with Combobox. You can find examples of custom autocomplete components on the examples page.

Not a searchable select

Autocomplete is not a searchable select, it is a text input with suggestions. Values are not enforced to be one of the suggestions – users can type anything. If you need a searchable select, use the Select component instead. To learn more about the differences between Autocomplete and Select, check the help center article.

Usage

Autocomplete provides users with a list of suggestions based on the input, however users are not limited to suggestions and can type anything.

Your favorite library

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

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

Loading state

Set loading prop to display a loading indicator. By default, the loader is displayed on the right side of the input. You can change the position with the loadingPosition prop to 'left' or 'right'. This is useful for async operations like API calls, searches, or validations:

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

function Demo() {
  return (
    <Autocomplete
      placeholder="Pick value"
      data={['React', 'Angular', 'Vue', 'Svelte']}
      loading
    />
  );
}

Controlled

The Autocomplete value must be a string; other types are not supported. The onChange function is called with a string value as a single argument.

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

function Demo() {
  const [value, setValue] = useState('');
  return <Autocomplete data={[]} value={value} onChange={setValue} />;
}

Uncontrolled

Autocomplete can be used with uncontrolled forms the same way as a native input element. Set the name attribute to include autocomplete value in FormData object on form submission. To control the initial value in uncontrolled forms, use the defaultValue prop.

Example usage of uncontrolled Autocomplete with FormData:

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

function Demo() {
  return (
    <form
      onSubmit={(event) => {
        event.preventDefault();
        const formData = new FormData(event.currentTarget);
        console.log('Autocomplete value:', formData.get('country'));
      }}
    >
      <Autocomplete
        label="Select your country"
        placeholder="Pick one"
        name="country"
        data={['United States', 'Canada', 'Mexico']}
        defaultValue="United States"
      />
      <button type="submit">Submit</button>
    </form>
  );
}

Select first option on change

Set the selectFirstOptionOnChange prop to automatically select the first option in the dropdown when the input value changes. This feature allows users to type a value and immediately press Enter to select the first matching option, without needing to press the arrow down key first.

Your favorite library

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

function Demo() {
  return (
    <Autocomplete
      label="Your favorite library"
      placeholder="Pick value or enter anything"
      selectFirstOptionOnChange
      data={['React', 'Angular', 'Vue', 'Svelte']}
    />
  );
}

autoSelectOnBlur

Set the autoSelectOnBlur prop to automatically select the highlighted option when the input loses focus. To see this feature in action: select an option with the up/down arrows, then click outside the input:

Your favorite library

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

function Demo() {
  return (
    <Autocomplete
      label="Your favorite library"
      placeholder="Pick value or enter anything"
      autoSelectOnBlur
      data={['React', 'Angular', 'Vue', 'Svelte']}
    />
  );
}

Data formats

Autocomplete data prop accepts data in one of the following formats:

Array of strings:

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

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

Array of groups with string options:

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

function Demo() {
  return (
    <Autocomplete
      data={[
        { group: 'Frontend', items: ['React', 'Angular'] },
        { group: 'Backend', items: ['Express', 'Django'] },
      ]}
    />
  );
}

Options filtering

By default, Autocomplete filters options by checking if the option label contains the input value. You can change this behavior with the filter prop. The filter function receives an object with the following properties as a single argument:

options – array of options or options groups, all options are in { value: string; label: string; disabled?: boolean } format
search – current search query
limit – value of the limit prop passed to Autocomplete

Example of a custom filter function that matches options by words instead of letter sequence:

Your country

import { Autocomplete, ComboboxItem, OptionsFilter } from '@mantine/core';

const optionsFilter: OptionsFilter = ({ options, search }) => {
  const splittedSearch = search.toLowerCase().trim().split(' ');
  return (options as ComboboxItem[]).filter((option) => {
    const words = option.label.toLowerCase().trim().split(' ');
    return splittedSearch.every((searchWord) => words.some((word) => word.includes(searchWord)));
  });
};

function Demo() {
  return (
    <Autocomplete
      label="Your country"
      placeholder="Pick value or enter anything"
      data={['Great Britain', 'Russian Federation', 'United States']}
      filter={optionsFilter}
    />
  );
}

Sort options

By default, options are sorted by their position in the data array. You can change this behavior with the filter function:

Your favorite library

import { Autocomplete, ComboboxItem, OptionsFilter } from '@mantine/core';

const optionsFilter: OptionsFilter = ({ options, search }) => {
  const filtered = (options as ComboboxItem[]).filter((option) =>
    option.label.toLowerCase().trim().includes(search.toLowerCase().trim())
  );

  filtered.sort((a, b) => a.label.localeCompare(b.label));
  return filtered;
};

function Demo() {
  return (
    <Autocomplete
      label="Your favorite library"
      placeholder="Pick value or enter anything"
      data={['4 – React', '1 – Angular', '3 – Vue', '2 – Svelte']}
      filter={optionsFilter}
    />
  );
}

Fuzzy search with fuse.js

You can implement fuzzy search using the fuse.js library to match options even with typos or partial matches:

Your favorite library

import { Autocomplete, ComboboxItem, OptionsFilter } from '@mantine/core';
import Fuse from 'fuse.js';

const optionsFilter: OptionsFilter = ({ options, search }) => {
  if (!search.trim()) {
    return options;
  }

  const fuse = new Fuse(options as ComboboxItem[], {
    keys: ['label'],
    threshold: 0.3,
    minMatchCharLength: 1,
  });

  return fuse.search(search).map((result) => result.item);
};

function Demo() {
  return (
    <Autocomplete
      label="Your favorite library"
      placeholder="Pick value or enter anything"
      data={['React', 'Angular', 'Vue', 'Svelte', 'Ember']}
      filter={optionsFilter}
    />
  );
}

Large data sets

The best strategy for large data sets is to limit the number of options that are rendered at the same time. You can do this with the limit prop. Note that if you use a custom filter function, you need to implement your own logic to limit the number of options in filter.

Example of Autocomplete with 100,000 options, 5 options are rendered at the same time:

100 000 options autocomplete

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

const largeData = Array(100_000)
  .fill(0)
  .map((_, index) => `Option ${index}`);

function Demo() {
  return (
    <Autocomplete
      label="100 000 options autocomplete"
      placeholder="Use limit to optimize performance"
      limit={5}
      data={largeData}
    />
  );
}

renderOption

The renderOption callback allows you to customize option rendering. It is called with an option object. The function must return a React node.

Employee of the month

import { Autocomplete, AutocompleteProps, Avatar, Group, Text } from '@mantine/core';

const usersData: Record<string, { image: string; email: string }> = {
  'Emily Johnson': {
    image: 'https://raw.githubusercontent.com/mantinedev/mantine/master/.demo/avatars/avatar-7.png',
    email: 'emily92@gmail.com',
  },
  'Ava Rodriguez': {
    image: 'https://raw.githubusercontent.com/mantinedev/mantine/master/.demo/avatars/avatar-8.png',
    email: 'ava_rose@gmail.com',
  },
  'Olivia Chen': {
    image: 'https://raw.githubusercontent.com/mantinedev/mantine/master/.demo/avatars/avatar-4.png',
    email: 'livvy_globe@gmail.com',
  },
  'Ethan Barnes': {
    image: 'https://raw.githubusercontent.com/mantinedev/mantine/master/.demo/avatars/avatar-1.png',
    email: 'ethan_explorer@gmail.com',
  },
  'Mason Taylor': {
    image: 'https://raw.githubusercontent.com/mantinedev/mantine/master/.demo/avatars/avatar-2.png',
    email: 'mason_musician@gmail.com',
  },
};

const renderAutocompleteOption: AutocompleteProps['renderOption'] = ({ option }) => (
  <Group gap="sm">
    <Avatar src={usersData[option.value].image} size={36} radius="xl" />
    <div>
      <Text size="sm">{option.value}</Text>
      <Text size="xs" opacity={0.5}>
        {usersData[option.value].email}
      </Text>
    </div>
  </Group>
);

function Demo() {
  return (
    <Autocomplete
      data={['Emily Johnson', 'Ava Rodriguez', 'Olivia Chen', 'Ethan Barnes', 'Mason Taylor']}
      renderOption={renderAutocompleteOption}
      maxDropdownHeight={300}
      label="Employee of the month"
      placeholder="Search for employee"
    />
  );
}

Nothing found message

The Autocomplete component does not support a nothing found message. It is designed to accept any string as a value, so it does not make sense to show a nothing found message. If you want to limit user input to suggestions, you can use a searchable Select component instead. To learn more about the differences between Autocomplete and Select, check the help center article.

Scrollable dropdown

By default, the options list is wrapped with ScrollArea.Autosize. You can control the dropdown max-height with the maxDropdownHeight prop if you do not change the default settings.

If you want to use native scrollbars, set withScrollArea={false}. Note that in this case, you will need to change the dropdown styles with Styles API.

With scroll area (default)

With native scroll

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

const data = Array(100)
  .fill(0)
  .map((_, index) => `Option ${index}`);

function Demo() {
  return (
    <>
      <Autocomplete
        label="With scroll area (default)"
        placeholder="Pick value or enter anything"
        data={data}
        maxDropdownHeight={200}
      />

      <Autocomplete
        label="With native scroll"
        placeholder="Pick value or enter anything"
        data={data}
        withScrollArea={false}
        styles={{ dropdown: { maxHeight: 200, overflowY: 'auto' } }}
        mt="md"
      />
    </>
  );
}

Group options

Your favorite library

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

function Demo() {
  return (
    <Autocomplete
      label="Your favorite library"
      placeholder="Pick value or enter anything"
      data={[
        { group: 'Frontend', items: ['React', 'Angular'] },
        { group: 'Backend', items: ['Express', 'Django'] },
      ]}
    />
  );
}

Disabled options

When an option is disabled, it cannot be selected and is ignored in keyboard navigation.

Your favorite library

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

function Demo() {
  return (
    <Autocomplete
      label="Your favorite library"
      placeholder="Pick value or enter anything"
      data={[
        { value: 'React' },
        { value: 'Angular' },
        { value: 'Vue', disabled: true },
        { value: 'Svelte', disabled: true },
      ]}
    />
  );
}

Combobox props

You can override Combobox props with comboboxProps. This is useful when you need to change some of the props that are not exposed by Autocomplete, for example withinPortal:

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

function Demo() {
  return <Autocomplete comboboxProps={{ withinPortal: false }} data={[]} />;
}

Change dropdown z-index

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

function Demo() {
  return <Autocomplete comboboxProps={{ zIndex: 1000 }} data={[]} />;
}

Inside Popover

To use Autocomplete inside popover, you need to set withinPortal: false:

import { Popover, Button, Autocomplete } from '@mantine/core';

function Demo() {
  return (
    <Popover width={300} position="bottom" withArrow shadow="md">
      <Popover.Target>
        <Button>Toggle popover</Button>
      </Popover.Target>
      <Popover.Dropdown>
        <Autocomplete
          label="Your favorite library"
          placeholder="Pick value or enter anything"
          data={['React', 'Angular', 'Vue', 'Svelte']}
          comboboxProps={{ withinPortal: false }}
        />
      </Popover.Dropdown>
    </Popover>
  );
}

Clearable

Set the clearable prop to display the clear button in the right section. The button is not displayed when:

The component does not have a value
The component is disabled
The component is read only

Clearable autocomplete

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

function Demo() {
  return (
    <Autocomplete
      clearable
      defaultValue="React"
      data={['React', 'Angular']}
      label="Clearable autocomplete"
      placeholder="Clearable autocomplete"
    />
  );
}

Clear section mode

The clearSectionMode prop determines how the clear button and rightSection are rendered:

'both' (default) – render both the clear button and rightSection
'rightSection' – render only the user-supplied rightSection, ignore clear button
'clear' – render only the clear button, ignore rightSection

clearSectionMode='both' (default)

clearSectionMode='rightSection'

clearSectionMode='clear'

import { CaretDownIcon } from '@phosphor-icons/react';
import { Autocomplete, Stack } from '@mantine/core';

function Demo() {
  return (
    <Stack>
      <Autocomplete
        label="clearSectionMode='both' (default)"
        placeholder="Pick value"
        data={['React', 'Angular', 'Vue', 'Svelte']}
        defaultValue="React"
        clearable
        rightSection={<CaretDownIcon size={16} />}
        clearSectionMode="both"
      />

      <Autocomplete
        label="clearSectionMode='rightSection'"
        placeholder="Pick value"
        data={['React', 'Angular', 'Vue', 'Svelte']}
        defaultValue="React"
        clearable
        rightSection={<CaretDownIcon size={16} />}
        clearSectionMode="rightSection"
      />

      <Autocomplete
        label="clearSectionMode='clear'"
        placeholder="Pick value"
        data={['React', 'Angular', 'Vue', 'Svelte']}
        defaultValue="React"
        clearable
        rightSection={<CaretDownIcon size={16} />}
        clearSectionMode="clear"
      />
    </Stack>
  );
}

Control dropdown opened state

You can control the dropdown opened state with the dropdownOpened prop. Additionally, you can use onDropdownClose and onDropdownOpen to listen to dropdown opened state changes.

Your favorite library

import { Autocomplete, Button } from '@mantine/core';
import { useDisclosure } from '@mantine/hooks';

function Demo() {
  const [dropdownOpened, { toggle }] = useDisclosure();
  return (
    <>
      <Button onClick={toggle} mb="md">
        Toggle dropdown
      </Button>

      <Autocomplete
        label="Your favorite library"
        placeholder="Pick value or enter anything"
        data={['React', 'Angular', 'Vue', 'Svelte']}
        dropdownOpened={dropdownOpened}
      />
    </>
  );
}

Dropdown position

By default, the dropdown is displayed below the input if there is enough space; otherwise it is displayed above the input. You can change this behavior by setting the position and middlewares props, which are passed down to the underlying Popover component.

Example of dropdown that is always displayed above the input:

Your favorite library

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

function Demo() {
  return (
    <Autocomplete
      label="Your favorite library"
      placeholder="Pick value or enter anything"
      data={['React', 'Angular', 'Vue', 'Svelte']}
      comboboxProps={{ position: 'top', middlewares: { flip: false, shift: false } }}
    />
  );
}

Dropdown animation

By default, dropdown animations are disabled. To enable them, you can set transitionProps, which will be passed down to the underlying Transition component.

Your favorite library

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

function Demo() {
  return (
    <Autocomplete
      label="Your favorite library"
      placeholder="Pick value or enter anything"
      data={['React', 'Angular', 'Vue', 'Svelte']}
      comboboxProps={{ transitionProps: { transition: 'pop', duration: 200 } }}
    />
  );
}

Dropdown padding

Zero padding

10px padding

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

function Demo() {
  return (
    <>
      <Autocomplete
        label="Zero padding"
        placeholder="Pick value or enter anything"
        data={['React', 'Angular', 'Vue', 'Svelte']}
        comboboxProps={{ dropdownPadding: 0 }}
      />
      <Autocomplete
        mt="md"
        label="10px padding"
        placeholder="Pick value or enter anything"
        data={['React', 'Angular', 'Vue', 'Svelte']}
        comboboxProps={{ dropdownPadding: 10 }}
      />
    </>
  );
}

Dropdown shadow

Your favorite library

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

function Demo() {
  return (
    <Autocomplete
      label="Your favorite library"
      placeholder="Pick value or enter anything"
      data={['React', 'Angular', 'Vue', 'Svelte']}
      comboboxProps={{ shadow: 'md' }}
    />
  );
}

Left and right sections

Autocomplete supports leftSection and rightSection props. These sections are rendered with absolute positioning inside the input wrapper. You can use them to display icons, input controls, or any other elements.

You can use the following props to control sections styles and content:

rightSection / leftSection – React node to render on the corresponding side of input
rightSectionWidth/leftSectionWidth – controls the width of the right section and padding on the corresponding side of the input. By default, it is controlled by the component size prop.
rightSectionPointerEvents/leftSectionPointerEvents – controls the pointer-events property of the section. If you want to render a non-interactive element, set it to none to pass clicks through to the input.

Your favorite library

import { Autocomplete } from '@mantine/core';
import { SquaresFourIcon } from '@phosphor-icons/react';

function Demo() {
  const icon = <SquaresFourIcon size={16} />;
  return (
    <>
      <Autocomplete
        data={['React', 'Angular', 'Vue']}
        leftSectionPointerEvents="none"
        leftSection={icon}
        label="Your favorite library"
        placeholder="Your favorite library"
      />
      <Autocomplete
        mt="md"
        data={['React', 'Angular', 'Vue']}
        rightSectionPointerEvents="none"
        rightSection={icon}
        label="Your favorite library"
        placeholder="Your favorite library"
      />
    </>
  );
}

Input props

Autocomplete component supports Input and Input.Wrapper component features and all input element props. The Autocomplete documentation does not include all features supported by the component – see the Input documentation to learn about all available features.

Input label

Input description

Variant

Default

Filled

Unstyled

Size

Radius

Label

With asterisk

Description

Error

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

function Demo() {
  return (
    <Autocomplete
      label="Input label"
      description="Input description"
      placeholder="Autocomplete placeholder"
      data={['React', 'Angular', 'Vue', 'Svelte']}
    />
  );
}

Read only

Set readOnly to make the input read only. When readOnly is set, Autocomplete will not show suggestions and will not call the onChange function.

Your favorite library

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

function Demo() {
  return (
    <Autocomplete
      label="Your favorite library"
      placeholder="Pick value or enter anything"
      data={['React', 'Angular', 'Vue', 'Svelte']}
      readOnly
    />
  );
}

Disabled

Set disabled to disable the input. When disabled is set, users cannot interact with the input and Autocomplete will not show suggestions.

Your favorite library

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

function Demo() {
  return (
    <Autocomplete
      label="Your favorite library"
      placeholder="Pick value or enter anything"
      data={['React', 'Angular', 'Vue', 'Svelte']}
      disabled
    />
  );
}

Error state

Boolean error

With error message

Invalid name

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

function Demo() {
  return (
    <>
      <Autocomplete
        label="Boolean error"
        placeholder="Boolean error"
        error
        data={['React', 'Angular', 'Vue', 'Svelte']}
      />
      <Autocomplete
        mt="md"
        label="With error message"
        placeholder="With error message"
        error="Invalid name"
        data={['React', 'Angular', 'Vue', 'Svelte']}
      />
    </>
  );
}

Styles API

Autocomplete supports the Styles API; you can add styles to any inner element of the component with the classNames prop. Follow the Styles API documentation to learn more.

Autocomplete

Description

Component Styles API

Hover over selectors to highlight corresponding elements

/*
 * Hover over selectors to apply outline styles
 *
 */

Get element ref

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

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

Accessibility

If Autocomplete is used without the label prop, it will not be announced properly by screen readers:

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

// Inaccessible input – screen reader will not announce it properly
function Demo() {
  return <Autocomplete />;
}

Set aria-label to make the input accessible. In this case the label will not be visible, but screen readers will announce it:

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

// Accessible input – it has aria-label
function Demo() {
  return <Autocomplete aria-label="My input" />;
}

If the label prop is set, the input will be accessible and it is not required to set aria-label:

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

// Accessible input – it has associated label element
function Demo() {
  return <Autocomplete label="My input" />;
}

TextInput

Combobox