Autocomplete

Autocomplete user input with any list of options

Import

Source

View source code

Docs

Edit this page

Package

@asuikit/core

Usage

Your favorite framework/library

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

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

Data prop

Autocomplete support two different data formats:

An array of strings
An array of objects with required value property and any other additional properties

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

Your favorite Rick and Morty character

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

Choose employee of the month

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

Only 2 options at a time

import { Autocomplete } from '@asuikit/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:

Your favorite framework/library

DropdownPosition

Top

Bottom

Flip

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

Your favorite framework/library

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

function Demo() {
  return (
    <Autocomplete
      maw={320}
      mx="auto"
      label="Your favorite framework/library"
      placeholder="Pick one"
      data={['React', 'Angular', 'Svelte', 'Vue']}
      transitionProps={{ transition: 'pop-top-left', duration: 80, timingFunction: 'ease' }}
    />
  );
}

With icon

Enter a hashtag

import { Autocomplete } from '@asuikit/core';
import { IconHash } from '@tabler/icons-react';

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

Invalid state and error

Your favorite frameworks/libraries

Field is required

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

Disabled without value

Disabled with value

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

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

Input props

Your favorite framework/library

Placeholder

Label

Description

Error

Variant

Radius

Size

Disabled

With asterisk

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

Up next

Checkbox – @asuikit/core

Autocomplete component props

Name	Type	Description
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
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
placeholder	string
portalProps	Omit<PortalProps, "children" \| "withinPortal">	Props to pass down to the portal when withinPortal is true
positionDependencies	any[]	useEffect dependencies to force update dropdown position
radius	number \| "xs" \| "sm" \| "md" \| "lg" \| "xl"	Key of theme.radius or any valid CSS value to set border-radius, theme.defaultRadius by default
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
transitionProps	Partial<Omit<TransitionProps, "mounted">>	Props added to Transition component that used to animate dropdown presence, use to configure duration and animation type, { duration: 0, transition: 'fade' } by default
value	string	Controlled input value
variant	Variants<"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

Name	Static selector	Description
dropdown	.asuikit-Autocomplete-dropdown	Dropdown element
item	.asuikit-Autocomplete-item	Item element, rendered inside dropdown
nothingFound	.asuikit-Autocomplete-nothingFound	Nothing found label
separator	.asuikit-Autocomplete-separator	Divider wrapper
separatorLabel	.asuikit-Autocomplete-separatorLabel	Separator Label
itemsWrapper	.asuikit-Autocomplete-itemsWrapper	Wraps all items in dropdown
wrapper	.asuikit-Autocomplete-wrapper	Root Input element
icon	.asuikit-Autocomplete-icon	Input icon wrapper on the left side of the input, controlled by icon prop
input	.asuikit-Autocomplete-input	Main input element
rightSection	.asuikit-Autocomplete-rightSection	Input right section, controlled by rightSection prop
root	.asuikit-Autocomplete-root	Root element
label	.asuikit-Autocomplete-label	Label element styles, defined by label prop
error	.asuikit-Autocomplete-error	Error element styles, defined by error prop
description	.asuikit-Autocomplete-description	Description element styles, defined by description prop
required	.asuikit-Autocomplete-required	Required asterisk element styles, defined by required prop

Learn more about Styles API

Build fully functional accessible web applications faster than ever

About

Contribute About Mantine Changelog Releases

Community

Chat on Discord Follow on Twitter Follow on GitHub GitHub discussions

Project

Mantine UI Documentation GitHub organization npm organization

Built by Vitaly Rtishchev and these awesome people

Join Discord community

Follow Mantine on Twitter