Autocomplete
A text input with type-ahead suggestions. Supports keyboard navigation, custom values, and validation states.
Basic Example
Controlled Value
Type to filter suggestions
Pre-selected Value
React is pre-selected
With Helper Text
Start typing to see suggestions
States
Error State
Please select a valid city
Disabled State
Allow Custom Values
When allowCustomValue is true (default), users can enter values not in the suggestions list and press Enter to confirm.
Type a custom tag and press Enter
Restrict to Suggestions
Set allowCustomValue=false to only allow selecting from suggestions.
Only values from the list are allowed
Limit Suggestions
Shows max 5 suggestions
Non-Clearable
Clear button is hidden
Props
| Name | Type | Default | Description |
|---|---|---|---|
label* | string | - | Label text for the input |
suggestions* | string[] | - | Array of suggestion strings to display |
placeholder | string | 'Type to search...' | Placeholder text when input is empty |
value | string | - | Controlled value of the input |
maxSuggestions | number | 10 | Maximum number of suggestions to display |
allowCustomValue | boolean | true | Allow entering values not in suggestions list |
clearable | boolean | true | Show clear button when input has value |
disabled | boolean | false | Whether the input is disabled |
error | string | - | Error message to display |
helperText | string | - | Helper text below input |
onChange | (value: string) => void | - | Callback when input value changes |
onSelect | (value: string) => void | - | Callback when a suggestion is selected |
onClear | () => void | - | Callback when input is cleared |
Keyboard Navigation
| Key | Action |
|---|---|
| ↓ Arrow Down | Open suggestions / Move to next suggestion |
| ↑ Arrow Up | Move to previous suggestion |
| Enter | Select highlighted suggestion / Confirm custom value |
| Escape | Close suggestions dropdown |
| Tab | Close dropdown and move to next element |
Usage Guidelines
When to use
- •When users need to select from a long list with type-ahead filtering
- •When the list of options is dynamic or loaded from an API
- •When users might need to enter custom values not in the list
- •For tagging or labeling interfaces
Best practices
- •Provide meaningful placeholder text that hints at expected input
- •Use helper text to explain how the autocomplete works
- •Set appropriate maxSuggestions to avoid overwhelming the user
- •Consider disabling custom values when input must match specific options
Accessibility
- •Full keyboard navigation (Arrow keys, Enter, Escape)
- •ARIA combobox pattern with listbox for suggestions
- •aria-expanded indicates dropdown state
- •aria-invalid for error states
- •Error messages announced with aria-live
- •Clear button has accessible label
Do's and Don'ts
✓ Do
- •Use for searchable lists with many options
- •Allow custom values when appropriate
- •Provide clear feedback when no results match
- •Use descriptive labels and placeholders
Start typing to see suggestions
✗ Don't
- •Don't use for short lists (use Select instead)
- •Don't use vague placeholder text
- •Don't show too many suggestions at once
- •Don't require exact matching without clear indication
Related Components
Select
For choosing from a predefined list
Text Input
For free-form text entry
Chip
For displaying selected tags