Component

Autocomplete

A text input with suggestions. The value is whatever the user types; picking a suggestion fills it in.

preview

React
"use client"

import { useState } from "react"
import Autocomplete from "@radui/ui/Autocomplete"

const CITIES = ["Amsterdam", "Athens", "Bangalore", "Barcelona", "Berlin", "Hyderabad", "Lisbon", "London", "Mumbai", "Paris"]

export default function AutocompleteExample() {
    const [city, setCity] = useState("")

    return (
        <Autocomplete.Root value={city} onValueChange={setCity}>
            <Autocomplete.Input aria-label="City" placeholder="Search cities" />
            <Autocomplete.Portal>
                <Autocomplete.Content>
                    {CITIES.map((name) => (
                        <Autocomplete.Item key={name} value={name}>{name}</Autocomplete.Item>
                    ))}
                </Autocomplete.Content>
            </Autocomplete.Portal>
        </Autocomplete.Root>
    )
}

Features

Free-text value: suggestions help but don't restrict what can be typed
Filters suggestions by what's typed and highlights the first match
Focus stays in the input; options are reached with aria-activedescendant
Enter or a click fills in the suggestion; Escape closes and keeps the text

API Documentation

Anatomy

Import all parts of the component and piece them together

React
import Autocomplete from "@radui/ui/Autocomplete"

export default () => {
    return (
        <Autocomplete.Root>
            <Autocomplete.Input />
            <Autocomplete.Clear />
            <Autocomplete.Portal>
                <Autocomplete.Content>
                    <Autocomplete.Group>
                        <Autocomplete.Item />
                    </Autocomplete.Group>
                    <Autocomplete.Empty />
                </Autocomplete.Content>
            </Autocomplete.Portal>
        </Autocomplete.Root>
    )
}

Root

Holds the input text and the suggestion list state.

Prop	Type	Default
value	string	--
defaultValue	string	""
onValueChange	(value: string) => void	--
open	boolean	--
onOpenChange	(open: boolean) => void	--
disabled	boolean	false
anchor	Element \| VirtualElement \| RefObject \| () => Element	--
positionMethod	"absolute" \| "fixed"	"fixed"
collisionAvoidance	{ side?, align?, fallbackAxisSide? }	--
sticky	boolean	false
disableAnchorTracking	boolean	false
filter	(label, query) => boolean \| null	--
limit	number	--
locale	Intl.LocalesArgument	--
readOnly	boolean	false
form	string	--
inputRef	Ref<HTMLSelectElement>	--
autoComplete	string	--
finalFocus	boolean \| RefObject \| () => HTMLElement	true
highlightItemOnHover	boolean	true
onItemHighlighted	(value, { index }) => void	--
loop	boolean	false
actionsRef	Ref<{ close(): void }>	--
autoHighlight	boolean \| 'always'	false
openOnInputClick	boolean	false
submitOnItemClick	boolean	false
mode	"list" \| "both" \| "inline" \| "none"	"list"

Input

The text input. Typing opens the suggestions; focus stays here while ArrowDown and ArrowUp move through them.

Prop	Type	Default
placeholder	string	--
asChild	boolean	false

Item

A suggestion. Its value is the text filled in when picked.

Prop	Type	Default
value	string	--
disabled	boolean	false

Empty

Shown when the typed text matches no option, such as "No results". It's outside the listbox and announced politely.

Prop	Type	Default
children	ReactNode	--

Clear

A button that clears the selection and the typed text, then returns focus to the input. It renders nothing while there's nothing to clear.

Prop	Type	Default
forceMount	boolean	false
children	ReactNode	×
aria-label	string	"Clear"
asChild	boolean	false

Keyboard Interactions

Shortcut	Description
`ArrowDown`	Opens the suggestions or moves to the next one.
`ArrowUp`	Moves to the previous suggestion.
`Enter`	Fills in the highlighted suggestion.
`Escape`	Closes the suggestions and keeps the text.

ARIA References

Reference	What Rad UI follows
Combobox pattern	The input has role="combobox" with aria-autocomplete="list", aria-expanded and aria-activedescendant pointing at the highlighted option.