Autocomplete

Autocomplete helps users to complete a text input by providing suggestions as they type.

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 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

• Site search
• Text input

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

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