DocsComponents

Autocomplete

Suggestions that help people find and select a value.

Country

Installation

Terminal

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

New here? Set up your project first. Styles, fonts, and required components are included.

Usage

Use multiple={false} for a single string value. Multiple selection uses an array of strings and displays selected values as chips.

Use the Code tab above for a complete example. The import follows your configured UI alias. See Theming to customize colors, spacing, and style slots.

State and callbacks

Selection is controlled: pass value and update it in onChange. Set multiple={false} for a string; multiple selection accepts an array of strings or a record of selected labels. The exported union types describe each callback signature.

The query is independent of selection. Omit query to let the component manage typed text, or supply query and onQueryChange to control it. There is no defaultValue selection API.

API reference

Generated from the installed TypeScript source. Defaults are the values declared by each function; a dash means no parameter default is declared. Forwarded props can use the receiving component’s default. Callback types show the exact arguments passed to your handler.

`Autocomplete`

Property	Type	Default
`error`	`React.ReactNode`	`—`
`floating`	`boolean`	`—`
`hint`	`React.ReactNode`	`—`
`icon`	`React.ReactNode`	`—`
`label`	`React.ReactNode`	`—`
`multiline`	`boolean`	`—`
`rows`	`number`	`—`
`classNames`	`AutocompleteTheme` Classes for the component's rendered parts. Applied after legacy theme overrides.	`—`
`allowCreate`	`boolean`	`false`
`direction`	`'auto' \| 'up' \| 'down'`	`'auto'`
`keepFocusOnChange`	`boolean`	`false`
`query`	`string`	`—`
`selectedPosition`	`'above' \| 'below' \| 'none'`	`'above'`
`showSelectedWhenNotInSource`	`boolean`	`false`
`showSuggestionsWhenValueIsSet`	`boolean`	`false`
`source`	`AutocompleteSource`	`emptySource`
`suggestionMatch`	`'disabled' \| 'start' \| 'anywhere' \| 'word' \| 'none'`	`'start'`
`theme`Deprecated alias	`AutocompleteTheme` Use classNames for style slots; use ThemeProvider for design tokens.	`—`
`ref`	`React.Ref<InputHandle>`	`—`
`multiple`	`((false) \| (true)) \| (true)`	`true`
`value`	`((string) \| (string[])) \| (Record<string, React.ReactNode>)`	`—`

Callbacks

Property	Type	Default
`onBlur`	`(event: React.FocusEvent<InputElement>, active?: string \| null) => void`	`—`
`onQueryChange`	`(query: string) => void`	`—`
`onChange`	`(((value: string, event: React.MouseEvent<HTMLElement> \| React.KeyboardEvent<HTMLElement>) => void) \| ((value: string[], event: React.MouseEvent<HTMLElement> \| React.KeyboardEvent<HTMLElement>) => void)) \| ((value: Record<string, React.ReactNode>, event: React.MouseEvent<HTMLElement> \| React.KeyboardEvent<HTMLElement>) => void)`	`—`

Additional defaults on inherited props: className = ''; disabled = false.

Style slots

Pass a map of Tailwind classes to classNames. Available keys:

active
autocomplete
focus
input
suggestion
suggestions
up
value
values

theme is the deprecated compatibility alias. When both are provided, classNames wins conflicting utilities within each slot. See Theming for tokens and override rules.

Exported TypeScript types

Expand a type to inspect its full declaration, including generic constraints, union branches, callback arguments, ref handles, and inherited props. Import these types from @/components/ui/material/autocomplete.

AutocompleteTheme

tsx

type AutocompleteTheme = Partial<
  Record<
    'active' | 'autocomplete' | 'focus' | 'input' | 'suggestion' | 'suggestions' | 'up' | 'value' | 'values',
    string
  >
>;

AutocompleteClassNames

tsx

type AutocompleteClassNames = AutocompleteTheme;

AutocompleteValue

tsx

type AutocompleteValue = string | string[] | Record<string, React.ReactNode>;

AutocompleteSource

tsx

type AutocompleteSource =
  | Record<string, React.ReactNode>
  | readonly (string | readonly [string, React.ReactNode])[];

AutocompleteEvent

tsx

type AutocompleteEvent = ChipEvent;

AutocompleteBaseProps

tsx

interface AutocompleteBaseProps
  extends Omit<InputProps, 'value' | 'defaultValue' | 'onChange' | 'onBlur' | 'theme' | 'multiple' | 'ref'> {
  allowCreate?: boolean;
  direction?: 'auto' | 'up' | 'down';
  keepFocusOnChange?: boolean;
  onBlur?: (event: React.FocusEvent<InputElement>, active?: string | null) => void;
  onQueryChange?: (query: string) => void;
  query?: string;
  selectedPosition?: 'above' | 'below' | 'none';
  showSelectedWhenNotInSource?: boolean;
  showSuggestionsWhenValueIsSet?: boolean;
  source?: AutocompleteSource;
  suggestionMatch?: 'disabled' | 'start' | 'anywhere' | 'word' | 'none';
  /** Classes for the component's rendered parts. Applied after legacy theme overrides. */
  classNames?: AutocompleteTheme;
  /** @deprecated Use classNames for style slots; use ThemeProvider for design tokens. */
  theme?: AutocompleteTheme;
  ref?: React.Ref<InputHandle>;
}

AutocompleteSingleProps

tsx

interface AutocompleteSingleProps extends AutocompleteBaseProps {
  multiple: false;
  value?: string;
  onChange?: (value: string, event: AutocompleteEvent) => void;
}

AutocompleteArrayProps

tsx

interface AutocompleteArrayProps extends AutocompleteBaseProps {
  multiple?: true;
  value?: string[];
  onChange?: (value: string[], event: AutocompleteEvent) => void;
}

AutocompleteObjectProps

tsx

interface AutocompleteObjectProps extends AutocompleteBaseProps {
  multiple?: true;
  value: Record<string, React.ReactNode>;
  onChange?: (value: Record<string, React.ReactNode>, event: AutocompleteEvent) => void;
}

AutocompleteProps

tsx

type AutocompleteProps = AutocompleteSingleProps | AutocompleteArrayProps | AutocompleteObjectProps;

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