Skip to content

Autocomplete

Suggestions that help people find and select a value.

Installation

Terminal
pnpm dlx shadcn@latest add \
  https://react-toolbox.io/r/autocomplete.json \
  https://react-toolbox.io/r/button.json

New here? Set up your project first. Styles, fonts, and required components are included. The command includes the components used by the examples below.

Usage

Use multiple={false} for a single string; multiple selection accepts a string array or a record of selected labels. Supply textValue when an option label contains custom content. Use suggestionMatch="disabled" for server-filtered results.

Composition

AutocompleteRoot supports object values and multiple selection with removable chips. Style parts with className or use render to substitute their elements.

Show composition code
tsx
'use client';
import { useState } from 'react';
import { Button } from '@/components/ui/material/button';
import { FontIcon } from '@/components/ui/material/font-icon';
import {
  AutocompleteRoot,
  AutocompleteLabel,
  AutocompleteInputGroup,
  AutocompleteChips,
  AutocompleteChip,
  AutocompleteChipRemove,
  AutocompleteSelection,
  AutocompleteInput,
  AutocompleteTrigger,
  AutocompleteClear,
  AutocompletePortal,
  AutocompletePositioner,
  AutocompletePopup,
  AutocompleteList,
  AutocompleteItem,
  AutocompleteItemIndicator,
  AutocompleteEmpty,
} from '@/components/ui/material/autocomplete';

const people = [
  { value: 'ada', label: 'Ada Lovelace', team: 'Engineering' },
  { value: 'grace', label: 'Grace Hopper', team: 'Engineering' },
  { value: 'alan', label: 'Alan Turing', team: 'Research' },
];
type Person = (typeof people)[number];
export default function AutocompleteComposition() {
  const [saved, setSaved] = useState<string[]>([]);
  return (
    <form
      className="max-w-lg space-y-4"
      onSubmit={(event) => {
        event.preventDefault();
        setSaved(new FormData(event.currentTarget).getAll('people').map(String));
      }}
    >
      <AutocompleteRoot items={people} multiple name="people" defaultValue={[people[0]]}>
        <AutocompleteLabel>Invite teammates</AutocompleteLabel>
        <AutocompleteInputGroup className="flex-wrap">
          <AutocompleteChips className="flex-1">
            <AutocompleteSelection>
              {(selected: Person[]) =>
                selected.map((person) => (
                  <AutocompleteChip key={person.value} aria-label={person.label}>
                    {person.label}
                    <AutocompleteChipRemove aria-label={`Remove ${person.label}`}>
                      <FontIcon value="cancel" aria-hidden className="text-[18px]" />
                    </AutocompleteChipRemove>
                  </AutocompleteChip>
                ))
              }
            </AutocompleteSelection>
            <AutocompleteInput placeholder="Find a teammate" className="min-w-40" />
          </AutocompleteChips>
          <AutocompleteClear aria-label="Clear teammates">
            <FontIcon value="close" aria-hidden />
          </AutocompleteClear>
          <AutocompleteTrigger aria-label="Show teammates">
            <FontIcon value="arrow_drop_down" aria-hidden />
          </AutocompleteTrigger>
        </AutocompleteInputGroup>
        <AutocompletePortal>
          <AutocompletePositioner>
            <AutocompletePopup>
              <AutocompleteEmpty>No teammates found.</AutocompleteEmpty>
              <AutocompleteList>
                {(person: Person) => (
                  <AutocompleteItem key={person.value} value={person} disabled={person.value === 'alan'}>
                    <span>
                      <span className="block">{person.label}</span>
                      <span className="text-toolbox-caption text-toolbox-text-secondary">{person.team}</span>
                    </span>
                    <AutocompleteItemIndicator className="ml-auto">
                      <FontIcon value="check" aria-hidden />
                    </AutocompleteItemIndicator>
                  </AutocompleteItem>
                )}
              </AutocompleteList>
            </AutocompletePopup>
          </AutocompletePositioner>
        </AutocompletePortal>
      </AutocompleteRoot>
      <Button type="submit" primary>
        Save teammates
      </Button>
      <output className="block text-toolbox-body">{saved.join(', ')}</output>
    </form>
  );
}

State and callbacks

  • Control selection with value/onChange, or use defaultValue for internal state and form reset. name and form submit the selected IDs.
  • Search text is independent: query/onQueryChange controls it. The popup manages its own visibility unless you supply open/onOpenChange.
  • When overriding AutocompleteInput's id, set the matching htmlFor on AutocompleteLabel.

API reference

Key props and defaults. Full types and inline documentation are included with the source in material/autocomplete.

Autocomplete

Property Type Default
allowCreate boolean false
clearable boolean

Show a control that clears the selected value(s).

false
defaultValue ((string) | (string[])) | (Record<string, React.ReactNode>) —
loading boolean false
multiple ((false) | (true)) | (true) true
onChange (((value: string, event: React.MouseEvent<HTMLElement> | React.KeyboardEvent<HTMLElement> | React.ChangeEvent<HTMLSelectElement>) => void) | ((value: string[], event: React.MouseEvent<HTMLElement> | React.KeyboardEvent<HTMLElement> | React.ChangeEvent<HTMLSelectElement>) => void)) | ((value: Record<string, React.ReactNode>, event: React.MouseEvent<HTMLElement> | React.KeyboardEvent<HTMLElement> | React.ChangeEvent<HTMLSelectElement>) => void) —
readOnly boolean

Keep selected values focusable and submitted while preventing edits and validation.

false
source AutocompleteSource emptySource
value ((string) | (string[])) | (Record<string, React.ReactNode>) —

Material guidelines

  • Keep a visible field label after a value is entered. Suggestions help complete that field; they should remain relevant to the current input.
  • Offer keyboard access to suggestions and communicate validation with helpful text, not color alone.

Material Design 1: Text fields