Autocomplete
This is currently experimental because we need more research to validate it.
Autocomplete helps users to complete a text input by providing suggestions as they type.
Sample HTML
<div class="ds_site-search ds_autocomplete" id="site-search-autocomplete">
<form role="search" class="ds_site-search__form" method="GET" action="/path/to/search/">
<label class="ds_label visually-hidden" for="site-search" id="site-search-label">Search</label>
<div id="autocomplete-status" class="visually-hidden"></div>
<div class="ds_input__wrapper ds_input__wrapper--has-icon">
<input aria-autocomplete="list" aria-expanded="false" aria-owns="autocomplete-suggestions" autocomplete="off" class="ds_input ds_site-search__input js-autocomplete-input" haspopup="true" id="site-search" name="q" placeholder="Search" required="" type="search" />
<input name="cat" value="sitesearch" hidden="" />
<button type="submit" class="ds_button">
<span class="visually-hidden">Search gov.scot</span>
<svg class="ds_icon" aria-hidden="true" role="img"><use href="/assets/images/icons/icons.stack.svg#search"></use></svg>
</button>
<div id="autocomplete-suggestions" class="ds_autocomplete__suggestions">
<ol class="ds_autocomplete__suggestions-list" role="listbox" aria-labelledby="site-search-label"></ol>
</div>
</div>
</form>
</div>
About this component
The autocomplete component is used to display suggested terms pulled from a data source while the user types into a field. The data source is usually a back-end service.
The list of suggestions is shown when the user types into the field and it is updated every time a character is entered. Text matching the user’s input is highlighted in each suggestion. The list is limited to a maximum of 6 suggestions. On small devices fewer suggestions might be shown, depending on the space available. If there are no suggestions, the list does not appear.
Selecting a suggestion will place its text in the input field and the list of suggestions will be hidden. Suggestions can be selected by clicking, tapping or by using the keyboard.
The suggestion list is also hidden if the user clicks away from the text input and suggestion list.
Live example
Type into the search input in this example to see how the autocomplete component behaves.
Why we use this component
Autocomplete is commonly used for search inputs. When used on a search input, autocomplete helps users to select a well-formed term which will help them find the information they need.
More generally, autocomplete helps users to:
- correctly complete a form field
- avoid spelling errors because terms do not need to be typed out in full
- reduce the time it takes to complete a form field
Related components
Website analytics
Autocomplete interactions can be tracked through custom events and the original page path. These custom events are added automatically by the Design System’s ‘tracking’ script.
Accessibility
The autocomplete component has been built to support assistive technology, such as screen readers, and can be operated with a keyboard, mouse or touch screen.
Keyboard support
Key | Action |
---|---|
Up arrow | Highlight the previous suggestion in the suggestion list. Go to the last suggestion if the user was on the first suggestion in the list. |
Down arrow | Highlight the next suggestion in the suggestion list. Go to the first suggestion if the user was on the last suggestion in the list. |
Enter | Select the currently highlighted suggestion and hide the suggestion list. |
Tab | Move focus to the next focusable item and hide the suggestion list. |
Escape | Clear the text input and hide the suggestion list. |
Implementation
The autocomplete component needs JavaScript enabled in the user’s browser. If a user does not have JavaScript enabled the text field will behave as normal, without the autocomplete enhancements.
Autocomplete expects there to be a suggestions endpoint to communicate with.
Set up an autocomplete by creating a new Autocomplete
object. It takes three parameters:
- a DOM element to use for the autocomplete
- the URL for the suggestions endpoint
- an optional object of customisation settings
The customisation settings can have the following properties:
suggestionMappingFunction
: a function to map the data returned from the endpoint to the format that the autocomplete will use to populate its optionsthrottleDelay
: amount of time to wait after a keypress before sending the request, to prevent sending many requests if someone is typing quickly (default is 100ms)minLength
: number of characters that need to be in the text input before requesting suggestions (default is 3)
Example JavaScript
const autocomplete = new window.DS.components.Autocomplete(
document.getElementById('my-autocomplete'),
'https://www.example.com/path/to/autocomplete?query=',
{
suggestionMappingFunction: function (suggestionsObj) {
return suggestionsObj.map(suggestionsObj => ({
key: suggestionsObj.key,
displayText: suggestionsObj.disp,
weight: suggestionsObj.wt,
type: suggestionsObj.disp_t,
category: suggestionsObj.cat
}
)),
minLength: 1;
}
});
autocomplete.init();
Feedback, help or support
If you need any help or want to give any feedback you can e-mail us at: designsystem@gov.scot