Chapter 13: Autocomplete

Core Idea

A free-form text input with optional suggestion autocompletion — unlike Combobox, the input value is not constrained to a selected item, making it the right choice for search boxes and filterable command lists rather than for a "pick exactly one of these" selection control.

Key Concepts

• Anatomy: Root → InputGroup (Input, Trigger, Icon, Clear, Value) + Portal → Backdrop, Positioner → Popup (Arrow, Status, Empty, List → Row → Item, Separator, Group → GroupLabel, Collection).
• Usage guideline — vs. Combobox: use Combobox instead when the selection must be remembered and free-form text isn't allowed; Autocomplete's suggestions only optionally complete what the user typed. Autocomplete is also the right base for filterable command palettes (items perform an action on click rather than "select").
• Filtering: filter prop (or the useFilter/useFilteredItems utility hooks) drives which items show; limit caps result count; virtualized for large lists; grid for a 2D grid navigation layout instead of a linear list.
• Highlighting: autoHighlight auto-highlights the best match as you type; keepHighlight / highlightItemOnHover control whether hover changes the highlighted item.
• Form participation: name, form, disabled, readOnly, required on Root — same data-valid/data-invalid/data-dirty/data-touched/data-filled/data-focused field-state attributes as other form controls (see ch009 Forms, ch023 Field).
• Accessible naming: requires a <label> or Field wrapper — no built-in visible label part (unlike Select/Combobox which have .Label).

Reference Tables

Part	Notable props	Notable data attributes
Root	value/onValueChange, open/onOpenChange, items, filter, filteredItems, mode, autoHighlight, keepHighlight, highlightItemOnHover, grid, virtualized, limit, itemToStringValue, locale, modal, actionsRef	—
Input / Trigger	disabled	data-popup-open, data-list-empty, data-valid/data-invalid, data-dirty, data-touched, data-filled, data-focused
Clear	nativeButton, keepMounted	data-visible, data-starting-style/data-ending-style
Positioner	side/sideOffset, align/alignOffset, anchor, collisionBoundary/collisionPadding/collisionAvoidance, sticky, positionMethod	data-anchor-hidden, data-empty, data-side, data-align
Item	value, onClick, index, nativeButton, disabled	data-highlighted, data-disabled
Status / Empty	—	rendered conditionally based on filter results / loading state

Key Takeaways

1. Default to Autocomplete for search boxes and command palettes; switch to Combobox the moment the product needs "remember exactly what was selected, reject free text."
2. Use grid + Row when suggestions are naturally 2D (e.g. emoji or color pickers), not a manually-built CSS grid over a linear List — grid mode changes keyboard navigation (arrow keys move in 2D) to match.
3. virtualized + limit together are the standard combo for large suggestion sets — set a limit even when virtualized, since filtering itself still has a cost.

Connects To

• ch019 (Combobox): the selection-preserving sibling — see its own Usage guidelines for the reverse comparison.
• ch009 (Forms) / ch023 (Field): naming, validation, and the shared field-state data attributes used throughout InputGroup parts.
• ch027 (Menu): Positioner/collisionBoundary props share the same positioning API family used by every anchored popup component.