Autocomplete

Experimental

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

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 options
  • throttleDelay: 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 character that need to be in the text input before requesting suggestions (default is 3)

Example JavaScript

const autocomplete = new Autocomplete(
    document.getElementById('site-search-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

Back to top