Autocomplete

Sample HTML

Show this section

<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 role="status" aria-live="polite" id="autocomplete-status" class="visually-hidden"></div>
        <div class="ds_input__wrapper  ds_input__wrapper--has-icon">
            <input aria-autocomplete="list"
                aria-haspopup="listbox"
                aria-owns="autocomplete-suggestions"
                autocomplete="off"
                class="ds_input  ds_site-search__input  js-autocomplete-input"
                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

You can use the autocomplete component to display suggested terms while the user types. The terms are usually pulled from a back-end service.

Typing into the text field makes a list of suggestions appear. The list of suggestions updates while the user types in the field. Each suggestion has text matching the user's input highlighted.

The list shows up to 6 suggestions. Devices with small screens might show fewer suggestions, depending on the space available.

Selecting a suggestion will place its text in the input field and hide the list of suggestions. Users can select suggestions by clicking, tapping or by using the keyboard.

If there are no suggestions, the list does not appear.

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.

Open this example in a new window

Why we use this component

Autocomplete is usually used for search inputs. Autocomplete helps users to select a term which will help them find what they need.

More generally, autocomplete helps users to:

• complete a form field
• avoid spelling errors because users do not need to type terms out in full
• reduce the time it takes to complete a form field

Related components

• Site search
• Text input

Website analytics

You can track autocomplete interactions through custom events and the original page path. The Design System’s ‘tracking’ script adds these custom events.

Accessibility

We have built the autocomplete component to support assistive technology, such as screen readers. It will work 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 field will behave as a normal text input.

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 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();