Autocomplete

Guidelines React

The Autocomplete component is a form control that combines a text input with a filtered dropdown list of suggestions, allowing selection or free-form entry.

When to use

• Select from large or dynamic lists where typing to filter reduces cognitive load (e.g., search fields, country/state selection, tag inputs).
• Support free-form input with guided suggestions.
• When users may know part of the desired value and benefit from real-time filtering.

When NOT to use

• For small, fixed lists (less than 15 options); use Select instead.
• For pure free-form text without suggestions; use Text Field.
• For multi-select without visual tags; consider Tag Group integration.
• When suggestions are not filterable or typing is unnecessary.

Properties

States

State	Description	Visual Indicators
Default	Default interactive state	Inherited from input
Hover	Cursor over object	Inherited from input/trigger
Focus	Keyboard focus (visible on Tab or arrow key navigation)	Inherited from input
Open	Suggestion list visible	Popover displayed
Disabled	Non-interactive	Inherited from input
Invalid	-	Validation error

Content Guidelines

• Placeholder: Guide typing (e.g., “Type to search”).
• Option labels: Concise, scannable, and match filter logic.
• No results: Helpful message (e.g., “No options found”).

Accessibility

• Use role="combobox" with aria-autocomplete="list" and aria-controls for the listbox.
• Input supports aria-activedescendant for highlighted option.
• List uses role="listbox" with role="option" on items.
• Announce results count and selection changes via live region.
• Support aria-required, aria-invalid, and aria-errormessage.

Support standard keyboard navigation

• Inherited from parent component