Autocomplete
Free text with suggestions.
Basic
The user can type any text. The list shows the items that match. The value does not have to be one of the items.
Groups
Pass grouped items to Root. Each group shows a heading above its items.
Sizes
Match the size of the buttons beside the field, and use lg only for a hero field. sm, md, and lg are 26, 36, and 44 pixels high.
sm · dense UI
md · default
lg · hero field
States
Use inset by default and line for light or inline editing, with one appearance per form. Hover and focus the fields to see those states.
inset · forms
No page has this title.
line · inline editing
No page has this title.
Usage
These are defaults, not laws. Break one when you have a good reason, or when it makes the design more cohesive or more interesting.
- Choose the input from the number of options and what the user picks.
Component Use it for Radio One choice from 2 or 3 options that stay visible. Select One choice from 4 to about 10 options, or fewer options when space is tight. Combobox One or more choices from a long list, with typing to filter. Autocomplete Free text, with suggestions that the user can ignore. Choicebox A choice where each option needs a description, such as a plan. Checkbox An on or off value in a form that the user submits. Switch A setting that applies at once. - The list opens when the user types or presses an arrow key, not on click.
API
Props that the library adds. Every part also takes all the Base UI props.
Autocomplete.InputGroup
| Prop | Type | Default | Description |
|---|---|---|---|
| size | 'sm' | 'md' | 'lg' | 'md' | Sets the text size, padding, and control height. |
| appearance | 'inset' | 'line' | 'inset' | Sets the field shape. Keep inset for forms. Use line for light or inline editing, such as renaming in place, filters, and quick settings. |
Autocomplete.Clear
| Prop | Type | Default | Description |
|---|---|---|---|
| aria-label | string | 'Clear' | The accessible name of the clear button. |
Autocomplete.Empty
| Prop | Type | Default | Description |
|---|---|---|---|
| children | ReactNode | 'No results' | The message when no item matches the input. |
Autocomplete.Popup
| Prop | Type | Default | Description |
|---|---|---|---|
| sideOffset | number | 4 | The gap between the input and the popup, in pixels. |
| container | HTMLElement | ShadowRoot | RefObject | null | – | The element that the popup renders into. The default is the document body. |