Autocomplete
Suggestions that help people find and select a value.
Installation
pnpm dlx shadcn@latest add \
https://react-toolbox.io/r/autocomplete.json \
https://react-toolbox.io/r/button.jsonNew 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
'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 usedefaultValuefor internal state and form reset.nameandformsubmit the selected IDs. - Search text is independent:
query/onQueryChangecontrols it. The popup manages its own visibility unless you supplyopen/onOpenChange. - When overriding
AutocompleteInput'sid, set the matchinghtmlForonAutocompleteLabel.
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 | booleanShow 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 | booleanKeep 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.