Stable in React

Autocomplete

An input that suggests options as you type.

Compare Autocomplete in all 5 frameworks

Loading React 19.3.1…

Hover a part or use it. The code follows. · Loading React…

224Tests passing in React · 0 failing

61.6 KiBSize

5.90 msOpen

2.60 msClose

0.99 MiBMemory

productdevbook and 18 upstream authors5 commits · last Nov 4

Install#

One package per framework. Autocomplete's parts come from it; the anatomy tab at the top shows how they nest.

bun add @▢▢▢▢/react

21 parts. The example uses 9 of them; the data does not say which are required.

Autocomplete.RootGroups all parts of the autocomplete.
Autocomplete.InputA text input to search for items in the list.
Autocomplete.PortalA portal element that moves the popup to a different part of the DOM.
Autocomplete.PositionerPositions the popup against the trigger.
Autocomplete.PopupA container for the list.
Autocomplete.EmptyRenders its children only when the list is empty.
Autocomplete.ListA list container for the items.
Autocomplete.CollectionRenders filtered list items.
Autocomplete.ItemAn individual item in the list.
Autocomplete.ArrowDisplays an element positioned against the anchor. Not in the example.
Autocomplete.BackdropAn overlay displayed beneath the popup. Not in the example.
Autocomplete.ClearClears the value when clicked. Not in the example.
Autocomplete.GroupGroups related items with the corresponding label. Not in the example.
Autocomplete.GroupLabelAn accessible label that is automatically associated with its parent group. Not in the example.
Autocomplete.IconAn icon that indicates that the trigger button opens the popup. Not in the example.
Autocomplete.InputGroupA wrapper for the input and its associated controls. Not in the example.
Autocomplete.RowDisplays a single row of items in a grid list. Not in the example.
Autocomplete.SeparatorA visual separator between items or groups. Not in the example.
Autocomplete.StatusDisplays a status message whose content changes are announced politely to screen readers. Not in the example.
Autocomplete.TriggerA button that opens the popup. Not in the example.
Autocomplete.ValueThe current value of the autocomplete. Not in the example.

Examples#

Common ways to put it to work. Each one runs live.

Items load while typing; Status shows the loading text.

AutocompleteAsync.tsx

Styling and accessibility#

The parts ship no styles. Style their states with these attributes; the CSS tab at the top has a sheet. The same CSS works in all five frameworks.

[data-popup-open]Present when the corresponding popup is open. On Input, Clear, InputGroup, Trigger.
[data-pressed]Present when the input is pressed. On Input, InputGroup, Trigger.
[data-disabled]Present when the component is disabled. On Input, Item, Clear, InputGroup, Trigger.
[data-readonly]Present when the component is readonly. On Input, InputGroup, Trigger.
[data-popup-side]Indicates which side the corresponding popup is positioned relative to its anchor. On Input, InputGroup, Trigger.
[data-required]Present when the component is required. On Input, Trigger.
[data-valid]Present when the component is in a valid state (when wrapped in Field.Root). On Input, InputGroup, Trigger.
[data-invalid]Present when the component is in an invalid state (when wrapped in Field.Root). On Input, InputGroup, Trigger.
[data-touched]Present when the component has been touched (when wrapped in Field.Root). On Input, InputGroup, Trigger.
[data-dirty]Present when the component's value has changed (when wrapped in Field.Root). On Input, InputGroup, Trigger.
[data-filled]Present when the component has a value (when wrapped in Field.Root). On Input, InputGroup, Trigger.
[data-focused]Present when the input is focused (when wrapped in Field.Root). On Input, InputGroup, Trigger.
[data-list-empty]Present when the corresponding items list is empty. On Input, InputGroup, Trigger.
[data-open]Present when the popup is open. On Positioner, Popup, Arrow, Backdrop.
[data-closed]Present when the popup is closed. On Positioner, Popup, Arrow, Backdrop.
[data-anchor-hidden]Present when the anchor is hidden. On Positioner, Popup.
[data-side]Indicates which side the popup is positioned relative to the trigger. On Positioner, Popup, Arrow.
[data-align]Indicates how the popup is aligned relative to specified side. On Positioner, Popup, Arrow.
[data-empty]Present when the items list is empty. On Positioner, Popup.
--available-widthThe available width between the trigger and the edge of the viewport. On Positioner.
--available-heightThe available height between the trigger and the edge of the viewport. On Positioner.
--anchor-widthThe anchor's width. On Positioner.
--anchor-heightThe anchor's height. On Positioner.
--transform-originThe coordinates that this element is anchored to. Used for animations and transitions. On Positioner.
[data-starting-style]Present when the popup begins animating in. On Popup, Backdrop, Clear.
[data-ending-style]Present when the popup is animating out. On Popup, Backdrop, Clear.
[data-highlighted]Present when the item is highlighted. On Item.
[data-uncentered]Present when the arrow is uncentered. On Arrow.
[data-visible]Present when the clear button is visible. On Clear.
[data-orientation]Indicates the orientation of the separator. On Separator.

Keyboard

ArrowDownOpens the list; with autoHighlight, highlights the first item On Input.
EnterFills the input with the highlighted item and runs its click handler On Item.
EnterWith no item highlighted, submits the form the input belongs to On Input.
EscapeCloses the list and keeps what was typed On Input.
TabCloses the list and moves on On Input.

Set for you

role="combobox", aria-expanded, aria-haspopup, aria-controls to the list while opena screen reader says the input has suggestions and whether they are shownInput
aria-autocomplete from modea screen reader knows whether text is completed inline, listed, or bothInput
aria-activedescendant to the highlighted itemthe highlight is read while focus stays in the inputInput
role="listbox" (role="grid" with grid)the suggestions are announced as a list of optionsList
role="option"each suggestion is read as an optionItem
role="status", aria-live="polite"loading and result counts are announced without moving focusStatus
role="status", aria-live="polite""no results" is announced as it appearsEmpty
aria-hidden="true"the decorative icon is not readIcon

API reference#

67 props across 21 parts, in React syntax, and className, style, render once for every part. Open a row to try it.

Filter props

Autocomplete · all parts

Shared propsEvery part that renders an element takes these.

classNameCSS class applied to the element, or a function that returns a class based on the component's state.string | ((state: State) => string | undefined)

styleStyle applied to the element, or a function that returns a style object based on the component's state.React.CSSProperties | ((state: State) => React.CSSProperties | undefined)

renderAllows you to replace the component's HTML element with a different tag, or compose it with another component.React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, State>

Use it in React#

What differs from the React API. Switch the framework at the top of the page.

@▢▢▢▢/react is the React 19 package. Its parts, props, data attributes and error messages are upstream Base UI's, and upstream's own tests run against it.

Parts
Each component is its own entry point and exports one namespace named after it.
```
import { Switch } from '@base-ui-next/react/switch'

export function Example() {
  return (
    <Switch.Root>
      <Switch.Thumb />
    </Switch.Root>
  )
}
```
A part renders the element its API reference names, such as a <span> for Switch.Root.
Props and events
Props and callbacks have upstream's names and signatures: onCheckedChange(checked, details), onOpenChange(open, details), onValueChange(value, details). details carries reason, event, cancel() and allowPropagation(). Native handlers are React's (onClick, onKeyDown), and event.preventBaseUIHandler() stops a part's own handler.
Styling
className takes a string or a function (state) => string; style takes an object or a function (state) => object. The state's data-* attributes are on the element for CSS.
render
render takes an element (render={<a href="/docs" />}) or a function (props, state) => element that spreads props on what it returns.
Refs
ref reaches the part's element. Imperative handles are ref props, as upstream: inputRef, and actionsRef ({ validate } on Field and Form, { unmount, close } on Dialog).
Binding
A part is controlled when its value prop (checked, open, value) is set, and uncontrolled with the default form (defaultChecked, defaultOpen, defaultValue). React has no two-way binding: pair the value with its change callback.
From @base-ui/react
Change the import from @base-ui/react/<component> to @▢▢▢▢/react/<component>.
From @base-ui/react
Nothing else changes: props, parts, data attributes and errors are the same.