Search autocomplete

Guiding principle: Give users control.

When to use this component

Search autocomplete shows the user search suggestions based on the characters they are typing in a search field.

This allows the user to browse search suggestions and gives them an overview of the website’s content.

This is also known as search autosuggest, typeahead, predictive search, search-as-you-type and query suggestions.

Successful implementation of search autocomplete can lead to:

• a reduction in the user’s mental load while typing
• fewer spelling or input errors
• better navigational accuracy

When to suggest

A list of search suggestions should appear when a user enters a valid character in the search input field.

Valid characters are defined depending on the application’s search parameters. The suggestions should appear or change as the user adds or removes characters.

If no search suggestions match the user’s input, then hide the menu list and let the user manually complete their entry.

Component features

The search autocomplete component includes:

A. divider separating the suggestion menu list from the search box
B. hover and active press states for each search suggestion
C. search suggestion with bolded text that completes the suggestion
D. menu list with up to 6 search suggestions
E. drop shadow contrasting the suggestion menu list with the page background

Example

---

This component does not currently include previous search history or a categorised scoped search (for example “[search term] in [category]”).

Search menu interaction states

Active typing

Search suggestions should appear once the user enters a valid character. The suggestions given will depend on:

• what the user types
• how many matches there are in the site’s content

Hover and selection

Users should be able to hover through the list of search suggestions with their keyboard or mouse on desktop. They can choose a suggestion by either clicking on it, or by pressing enter when hovered over it. Choosing a suggestion then prompts the search to run, bringing the user to the search results page for the chosen term.

Example - Hover state

---

Example - Active select state

---

Example - Selected and submitted search

---

The full menu list should always appear above the fold and should be in the centre of focus.

Best practices

Do

• include up to 4 to 6 search suggestions
• show suggestions as soon as the user enters the first valid character
• suggest terms or phrases that are short, and easy to read and scan
• bold the portion of the suggestion that completes the user’s entered text
• highlight the selected search suggestion with an active state
• use a white page background to help show the contrast of the menu list
• for header-based search, add a darkened page overlay to the menu list to increase its visibility

Don’t

• bold the portion of text in the suggestions that matches what the user has typed
• use scrollbars in the suggestion menu list
• add extra visual elements like icons, padding, separators or alternating row colours
• exceed 6 suggestions — users will ignore the suggestions and it will slow down the search process

Do this

---

Don't do this

---

Don't do this

---

Technical specifications

Usage

To use the search autocomplete component in your project, follow these steps:

1. Download the ontario-search.js file from the repository.
2. Import the ontario-search.js file into your project using a <script> tag (for example <script src="path/to/ontario-search.js"></script>)
3. Declare your custom suggestion list as an array within the customSuggestions variable in the JavaScript file.
4. Call the function addSuggestions and add the customSuggestions as an argument to the function. Adding the addSuggestions(customSuggestions) function call within the load function ensures that the custom suggestions load properly into the autocomplete component when the page fully loads.

Example

The example shows one way to implement the component. You can replace the example with your own code.

 window.addEventListener('load', () => {
       const customSuggestions = [
    "Suggestion 1",
           "Suggestion 2",
           "Suggestion 3",
       ];
       addSuggestions(customSuggestions);
 });

Accessibility

Users can interact with the autocomplete component in multiple ways:

• up and down arrow keys move focus between items when the suggestion menu list is expanded
• pressing enter or clicking the mouse selects the search suggestion, adding it to the search field and completing the search
• esc key closes the drop-down menu

Focus Management

The search autocomplete component has a built-in focus management system that will highlight suggestions as the user navigates through them with their keyboard (up and down arrows) or mouse (clicking and hovering).

The focus management system responds and adapts to the user’s choice of interaction. This means the user can switch back and forth between using their keyboard or their mouse to choose a suggestion.

Attributes

In HTML, the role of a Searchbox is often designated as a combobox for accessibility purposes because it combines features of both a text input field and a dropdown list. A combobox allows users to interact with it using both keyboard and mouse. This provides flexibility for different interaction preferences and accessibility needs.

Aria-Controls

Use aria-controls to establish a connection between an input field and the element it influences or owns. This attribute helps assistive technologies understand the relationship between the input field and its associated content.

Aria-autocomplete

The aria-autocomplete property is crucial for defining the behaviour of the search autocomplete feature. For search autocomplete, use the list model (aria-autocomplete=”list”).

This presents a collection of possible values in a separate element that appears below the search input field, helping users choose a suggestion.

Autocomplete

Set the autocomplete attribute to false to make sure that the browser’s autocomplete functionality does not interfere with the design system autocomplete component.

Aria-haspopup

Include aria-haspopup=”list” to show that the search input field triggers a list with suggestions.

Aria-expanded

Utilise the aria-expanded state on the search input field to communicate the display status of the suggestion menu list.

Example

<input
    type="search"
    name="search"
    id=""
    autocomplete="off"
    aria-autocomplete="list"
    aria-controls="suggestion-list"
    aria-expanded="false"
    role="combobox"
    class="ontario-input ontario-search__input"
/>

The example shows the search input field configured with aria-autocomplete="list" and aria-haspopup="list". This indicates that it provides an autocomplete suggestion list, displayed in a separate popup.

To denote that the input field manages the list of autocomplete suggestions:

• set aria-controls=”suggestion-list’ on the search input field to show that it controls the suggestion menu list with the ID "suggestion-list"
• structure the associated popup element as a <ul> containing individual suggestion options, represented as <li> elements
• give each suggestion <li> element role="option" to indicate its purpose as an option within the list

In addition, set aria-expanded="false" on the search input field to show that the suggestion menu list is currently hidden or collapsed. When the suggestion menu list is expanded, aria-expanded should dynamically change to "true".