Autocomplete
Makes use of Reka UI Dialog
Basic example
This example asks you to select your favorite fruit and provides suggestions as you type. By default, the autocomplete allows free text entry and does not force the user to choose from the list of options.
value: [empty]
Custom item rendering
This autocomplete demonstrates customizing the display of suggestion items, in this case splitting an address into two lines.
When using this feature, be sure that each suggestion differentiates between the user's typed text and the additional suggested text, highlighting the latter for easy scanning. We provide an autocomplete suggestion text component that handles this for you and can support multiple lines of text.
To avoid overwhelming the user with choices, the number of suggestions displayed is limited to five items.
value: [empty]
Requiring a selection
In some cases, we want to require the user to select from the provided list of suggestions rather than allowing free text entry.
value: [empty]
Hidden label and limited width
In some cases, an autocomplete may appear in a narrow width layout. The suggestions list on desktop, however, is not constrained by this. Try searching for "solar" or "heat pump".
The label for the autocomplete is also hidden visually here, but will still be announced by screen readers.
value: [empty]
Error state
Message
value: [empty]
Disabled state
Focus overlay
When the autocomplete is being used as a navigation tool, for example in a site search, it can be helpful to minimize other distractions on the page to allow the user to focus on selecting the right option. This focus overlay accomplishes that by dimming the rest of the page when the autocomplete is open.
value: [empty]
EsAutocomplete props
Required
- Name
label
- Type
String
- Default
- n/a
- Description
- Required. Label text for the input. Also used as the accessible title of the mobile takeover.
- Name
suggestions
- Type
Array
- Default
- n/a
- Description
- Required. Array of suggestion objects to display, each with id and text keys and an optional value key.
Optional
- Name
autocomplete
- Type
String
- Default
off
- Description
- The input's autocomplete token. 'off' keeps the browser's own saved-value dropdown from competing with the suggestion list. A field that maps to a real autofill token — 'street-address', 'name', 'email' — can set it to trade the other way and let the browser offer a saved value.
- Name
clearText
- Type
String
- Default
Clear
- Description
- Accessible label for the X button that clears the input. The button appears whenever the input has text.
- Name
closeText
- Type
String
- Default
Close
- Description
- Text for the button that closes the full-screen takeover on mobile, keeping whatever is in the input.
- Name
delay
- Type
Number
- Default
300
- Description
- Milliseconds to debounce typing before the 'complete' event is emitted.
- Name
disabled
- Type
Boolean
- Default
false
- Description
- When disabled, the input has a gray background and cannot be interacted with.
- Name
helpText
- Type
String
- Default
Type your search and select from dropdown suggestions.
- Description
- Hint read out by screen readers when the input takes focus.
- Name
labelSrOnly
- Type
Boolean
- Default
false
- Description
- Visually hides the label so the autocomplete can stand on its own, described only by its placeholder. The label is still announced to screen readers.
- Name
minChars
- Type
Number
- Default
1
- Description
- Minimum number of characters (after trimming) before the 'complete' event is emitted and suggestions are shown.
- Name
noResultsText
- Type
String
- Default
No results found
- Description
- Message shown inside the suggestions panel once a search has come back with no suggestions. Never shown while a search is still in flight (promptText shows instead).
- Name
placeholder
- Type
String
- Default
- n/a
- Description
- Text to display inside the input when it is empty.
- Name
promptText
- Type
String
- Default
Type for suggestions
- Description
- Message shown inside the suggestions panel when there is nothing else to show: before typing begins, below minChars, or while the first search is in flight.
- Name
required
- Type
Boolean
- Default
false
- Description
- When true, a red asterisk is displayed next to the label and a default error message is available.
- Name
showOverlayOnFocus
- Type
Boolean
- Default
false
- Description
- On desktop, dims the rest of the page with an overlay while the input has focus. Suits a standalone primary search (e.g. site search in a sticky header); leave off for a field within a larger form, where the overlay would obscure sibling fields.
- Name
state
- Type
Boolean | null
- Default
null
- Description
- Specifies the validity of the input. Can be true (success), false (error), or null (default).
- Name
suggestionCountText
- Type
Function
- Default
(count) => '{count} suggestions available'
- Description
- Builds the screen-reader announcement made when suggestions arrive, given the number of suggestions displayed (after the display cap and the row trim). An empty result announces noResultsText instead.
- Name
triggerHelpText
- Type
String
- Default
Opens a search with suggestions as you type.
- Description
- Hint read out by screen readers for the trigger field on mobile (which opens the full screen takeover on tap rather than taking text directly).
EsAutocomplete events
- Name
blur
- Payload
—
- Description
- Emitted when the user leaves the field (e.g. focus moving to another control, a click outside) so form validation can occur.
- Name
complete
- Payload
query: string
- Description
- Emitted (debounced) when the user has typed at least minChars characters. Fetch or filter your suggestions in response and update the 'suggestions' prop.
- Name
select
- Payload
suggestion
- Description
- Emitted when a suggestion is chosen, by click/tap or by pressing Enter on a highlighted suggestion. The full suggestion object is passed, including its 'value' payload if provided.
EsAutocomplete slots
- Name
item
- Slot props
suggestion, query
- Description
- Custom renderer for each suggestion. When not provided, the suggestion text is rendered with the predictive portion bolded. Use the EsAutocompleteSuggestionText component to apply the same predictive bolding to your own text (see the custom item rendering example).
- Name
errorMessage
- Slot props
- n/a
- Description
- Error message shown below the input when 'state' is false.
- Name
message
- Slot props
- n/a
- Description
- Muted helper message shown below the input when there is no error.