Skip to main content

Autosuggest

Autosuggests are used to suggest options for answers by searching code lists such as, addresses, countries, languages, nationalities, etc.

How to use

Autosuggest functionality can be created using the input component and adding the necessary parameters.

To use this component it is advised that autocomplete is switched off by setting the autocomplete parameter to off.

Using a JSON file

Open this example in a new tab  
<div class="grid grid--gutterless">
  <div class="grid__col col-8@m">
    <div class="field">
      <label class="label  label--with-description " for="country-of-birth" id="country-of-birth-label">Current name of country
      </label>
      <span id="country-of-birth-label-description-hint" class="label__description  input--with-description">
        Enter your own answer or select from suggestions
      </span>
      <div id="country-of-birth-container" class="js-autosuggest js-address-not-editable  autosuggest-input " data-instructions="Use up and down keys to navigate suggestions once you&#39;ve typed more than two characters. Use the enter key to select a suggestion. Touch device users, explore by touch or with swipe gestures." data-aria-you-have-selected="You have selected" data-aria-min-chars="Enter 3 or more characters for suggestions." data-aria-one-result="There is one suggestion available." data-aria-n-results="There are {n} suggestions available." data-aria-limited-results="Results have been limited to 10 suggestions. Type more characters to improve your search" data-more-results="Continue entering to improve suggestions" data-results-title="Suggestions" data-no-results="No suggestions found. You can enter your own answer" data-type-more="Continue entering to get suggestions" data-autosuggest-data="https://gist.githubusercontent.com/rmccar/c123023fa6bd1b137d7f960c3ffa1fed/raw/4dede1d6e757cf0bb836228600676c62ceb4f86c/country-of-birth.json">
        <input type="text" id="country-of-birth" class="input input--text input-type__input js-autosuggest-input " autocomplete="off" aria-describedby="country-of-birth-label-description-hint" />
        <div class="autosuggest-input__results js-autosuggest-results">
          <header class="autosuggest-input__results-title u-fs-s">Suggestions</header>
          <ul class="autosuggest-input__listbox js-autosuggest-listbox" role="listbox" id="country-of-birth-listbox" aria-labelledby="country-of-birth-label" tabindex="-1"></ul>
        </div>
        <div class="autosuggest-input__instructions u-vh js-autosuggest-instructions" id="country-of-birth-instructions" tabindex="-1">Use up and down keys to navigate suggestions once you&#39;ve typed more than two characters. Use the enter key to select a suggestion. Touch device users, explore by touch or with swipe gestures.</div>
        <div class="autosuggest-input__status u-vh js-autosuggest-aria-status" aria-live="assertive" role="status" tabindex="-1"></div>
      </div>
    </div>
  </div>
</div>
Nunjucks macro options
Name Type Required Description
autosuggestData string true URL of the JSON file with the autosuggest data that needs to be searched
APIDomain string false Set an api domain when using an external API to suggest results
APIDomainBearerToken string false Set a bearer token for api authorization on the AIMS address api. Defaults to basic auth
allowMultiple boolean false Allows the component to accept multiple selections
instructions string true Instructions on how to use the autosuggest that will be read out by screenreaders
ariaYouHaveSelected string true Aria message to tell the user that they have selected an answer
ariaMinChars string true Aria message to tell the user how many charecters they need to enter before autosuggest will start
ariaResultsLabel string true Aria message to tell the user that suggestions are available
ariaOneResult string true Aria message to tell the user there is only one suggestion left
ariaNResults string true Aria message to tell the user how many suggestions are left
ariaLimitedResults string true Aria message to tell the user if the results have been limited and what they are limited to
ariaGroupedResults string true Aria message to tell the user about a grouped result e.g There are {n} for {x}
groupCount string true Aria message to tell the user the number of addresses in a group e.g. {n} addresses
moreResults string true Aria message to tell the user to continue to type to refine suggestions
noResults string true message to tell the user there are no results
tooManyResults string true message to tell the user there are too many results to display and the user should refine the search
typeMore string true message to encourage the user to enter more characters to get suggestions
resultsTitle string true Title of results to be displayed on screen at the top of the results
errorTitle string false Error message title displayed in the error panel
errorMessageEnter string false Error message description displayed in the error panel when the input is empty
errorMessageSelect string false Error message description displayed in the error panel when a suggestion has not been selected
errorMessageAPI string false Error message displayed when the API has failed during a search
errorMessageAPILinkText string false Link text used to toggle to a manual mode when using the address macro
isEditable boolean false Used with the address macro to invoke population of manual fields upon selection of suggestion
options Object<Options> false Option to provide key value pairs that will be added as data attributes to the component that will be added as parameters to the address index api
mandatory boolean false Set the autosuggest input to be mandatory and use client side validation for empty form submission

Options

Name Type Required Description
regionCode string false Sets the provided region code e.g. en-gb
adressType string false Sets the provided address type e.g. resedential
oneYearAgo string false If “true” will set a query parameter of epoch=75 
{% from "components/input/_macro.njk" import onsInput %}
<div class="grid grid--gutterless">
    <div class="grid__col col-8@m">
        {{ onsInput({
            "id": "country-of-birth",
            "label": {
                "text": "Current name of country",
                "description": "Enter your own answer or select from suggestions",
                "id": "country-of-birth-label"
            },
            "autocomplete": "off",
            "autosuggest":{
                "instructions": "Use up and down keys to navigate suggestions once you\'ve typed more than two characters. Use the enter key to select a suggestion. Touch device users, explore by touch or with swipe gestures.",
                "ariaYouHaveSelected": "You have selected",
                "ariaMinChars": "Enter 3 or more characters for suggestions.",
                "ariaResultsLabel": "Country suggestions",
                "ariaOneResult": "There is one suggestion available.",
                "ariaNResults": "There are {n} suggestions available.",
                "ariaLimitedResults": "Results have been limited to 10 suggestions. Type more characters to improve your search",
                "moreResults": "Continue entering to improve suggestions",
                "resultsTitle": "Suggestions",
                "autosuggestData": "https://gist.githubusercontent.com/rmccar/c123023fa6bd1b137d7f960c3ffa1fed/raw/4dede1d6e757cf0bb836228600676c62ceb4f86c/country-of-birth.json",
                "noResults": "No suggestions found. You can enter your own answer",
                "typeMore": "Continue entering to get suggestions"
            }
        }) }}
    </div>
</div>

This example is powered by a JavaScript library called Fuse.js  .

Response object

The autosuggests expect the response from the library to return the results as JSON objects in an array.

AutosuggestResultItem

The AutosuggestResultItem should consist of at least a key corresponding to the searched language (e.g. en) with its corresponding value.

Example response

{ "results": [ { "en": "United Kingdom", "cy": "Deyrnas Unedig" } ], "totalResults": 1 }

The autosuggest component sends a searchFields parameter in it’s query string that matches the lang attribute on the <html> element of the page.

The autosuggest component will search the cy or the en data to find results depending on the searchFields parameter.

Multiple selections

The autosuggest component allows for multiple suggestions and selections by passing in the parameter allowMultiple: "true".

Open this example in a new tab  
<div class="grid grid--gutterless">
  <div class="grid__col col-8@m">
    <div class="field">
      <label class="label  label--with-description " for="country-of-birth" id="country-of-birth-label">Passport
      </label>
      <span id="country-of-birth-label-description-hint" class="label__description  input--with-description">
        Enter your own answer or select from suggestions. You can enter multiple countries if you have a passport for more than one.
      </span>
      <div id="country-of-birth-container" class="js-autosuggest js-address-not-editable  autosuggest-input " data-instructions="Use up and down keys to navigate suggestions once you&#39;ve typed more than two characters. Use the enter key to select a suggestion. Touch device users, explore by touch or with swipe gestures." data-aria-you-have-selected="You have selected" data-aria-min-chars="Enter 3 or more characters for suggestions." data-aria-one-result="There is one suggestion available." data-aria-n-results="There are {n} suggestions available." data-aria-limited-results="Results have been limited to 10 suggestions. Type more characters to improve your search" data-more-results="Continue entering to improve suggestions" data-results-title="Suggestions" data-no-results="No suggestions found. You can enter your own answer" data-type-more="Continue entering to get suggestions" data-allow-multiple="true" data-autosuggest-data="https://gist.githubusercontent.com/rmccar/c123023fa6bd1b137d7f960c3ffa1fed/raw/4dede1d6e757cf0bb836228600676c62ceb4f86c/country-of-birth.json">
        <input type="text" id="country-of-birth" class="input input--text input-type__input js-autosuggest-input " autocomplete="off" aria-describedby="country-of-birth-label-description-hint" />
        <div class="autosuggest-input__results js-autosuggest-results">
          <header class="autosuggest-input__results-title u-fs-s">Suggestions</header>
          <ul class="autosuggest-input__listbox js-autosuggest-listbox" role="listbox" id="country-of-birth-listbox" aria-labelledby="country-of-birth-label" tabindex="-1"></ul>
        </div>
        <div class="autosuggest-input__instructions u-vh js-autosuggest-instructions" id="country-of-birth-instructions" tabindex="-1">Use up and down keys to navigate suggestions once you&#39;ve typed more than two characters. Use the enter key to select a suggestion. Touch device users, explore by touch or with swipe gestures.</div>
        <div class="autosuggest-input__status u-vh js-autosuggest-aria-status" aria-live="assertive" role="status" tabindex="-1"></div>
      </div>
    </div>
  </div>
</div>
Nunjucks macro options
Name Type Required Description
autosuggestData string true URL of the JSON file with the autosuggest data that needs to be searched
APIDomain string false Set an api domain when using an external API to suggest results
APIDomainBearerToken string false Set a bearer token for api authorization on the AIMS address api. Defaults to basic auth
allowMultiple boolean false Allows the component to accept multiple selections
instructions string true Instructions on how to use the autosuggest that will be read out by screenreaders
ariaYouHaveSelected string true Aria message to tell the user that they have selected an answer
ariaMinChars string true Aria message to tell the user how many charecters they need to enter before autosuggest will start
ariaResultsLabel string true Aria message to tell the user that suggestions are available
ariaOneResult string true Aria message to tell the user there is only one suggestion left
ariaNResults string true Aria message to tell the user how many suggestions are left
ariaLimitedResults string true Aria message to tell the user if the results have been limited and what they are limited to
ariaGroupedResults string true Aria message to tell the user about a grouped result e.g There are {n} for {x}
groupCount string true Aria message to tell the user the number of addresses in a group e.g. {n} addresses
moreResults string true Aria message to tell the user to continue to type to refine suggestions
noResults string true message to tell the user there are no results
tooManyResults string true message to tell the user there are too many results to display and the user should refine the search
typeMore string true message to encourage the user to enter more characters to get suggestions
resultsTitle string true Title of results to be displayed on screen at the top of the results
errorTitle string false Error message title displayed in the error panel
errorMessageEnter string false Error message description displayed in the error panel when the input is empty
errorMessageSelect string false Error message description displayed in the error panel when a suggestion has not been selected
errorMessageAPI string false Error message displayed when the API has failed during a search
errorMessageAPILinkText string false Link text used to toggle to a manual mode when using the address macro
isEditable boolean false Used with the address macro to invoke population of manual fields upon selection of suggestion
options Object<Options> false Option to provide key value pairs that will be added as data attributes to the component that will be added as parameters to the address index api
mandatory boolean false Set the autosuggest input to be mandatory and use client side validation for empty form submission

Options

Name Type Required Description
regionCode string false Sets the provided region code e.g. en-gb
adressType string false Sets the provided address type e.g. resedential
oneYearAgo string false If “true” will set a query parameter of epoch=75 
{% from "components/input/_macro.njk" import onsInput %}
<div class="grid grid--gutterless">
    <div class="grid__col col-8@m">
        {{ onsInput({
            "id": "country-of-birth",
            "label": {
                "text": "Passport",
                "id": "country-of-birth-label",
                "description": "Enter your own answer or select from suggestions. You can enter multiple countries if you have a passport for more than one."
            },
            "autocomplete": "off",
            "autosuggest":{
                "instructions": "Use up and down keys to navigate suggestions once you\'ve typed more than two characters. Use the enter key to select a suggestion. Touch device users, explore by touch or with swipe gestures.",
                "ariaYouHaveSelected": "You have selected",
                "ariaMinChars": "Enter 3 or more characters for suggestions.",
                "ariaResultsLabel": "Passport suggestions",
                "ariaOneResult": "There is one suggestion available.",
                "ariaNResults": "There are {n} suggestions available.",
                "ariaLimitedResults": "Results have been limited to 10 suggestions. Type more characters to improve your search",
                "moreResults": "Continue entering to improve suggestions",
                "resultsTitle": "Suggestions",
                "allowMultiple": "true",
                "autosuggestData": "https://gist.githubusercontent.com/rmccar/c123023fa6bd1b137d7f960c3ffa1fed/raw/4dede1d6e757cf0bb836228600676c62ceb4f86c/country-of-birth.json",
                "noResults": "No suggestions found. You can enter your own answer",
                "typeMore": "Continue entering to get suggestions"
            }
        }) }}
    </div>
</div>

Using the address API

Important information:
This component requires documentation.

Open this example in a new tab  
<div class="grid grid--gutterless">
  <div class="grid__col col-8@m js-address-autosuggest">
    <div class="field">
      <label class="label js-autosuggest-label " for="address-lookup" id="address-lookup-label">Enter address or postcode and select from results
      </label>
      <div id="address-lookup-container" class=" js-address-not-editable  autosuggest-input js-address-not-editable" data-instructions="Use up and down keys to navigate suggestions once you&#39;ve typed more than two characters. Use the enter key to select a suggestion. Touch device users, explore by touch or with swipe gestures." data-aria-you-have-selected="You have selected" data-aria-min-chars="Enter 3 or more characters for suggestions." data-aria-one-result="There is one suggestion available." data-aria-n-results="There are {n} suggestions available." data-aria-limited-results="Results have been limited to 10 suggestions. Type more characters to improve your search" data-more-results="Enter more of the address to improve results" data-results-title="Select an address" data-no-results="No results found. Try entering a different part of the address" data-type-more="Enter more of the address to get results" data-api-domain="https://whitelodge-ai-api.census-gcp.onsdigital.uk" data-error-title="There is a problem with your answer" data-error-enter="Enter an address" data-error-select="Select an address" data-aria-grouped-results="There are {n} addresses for {x}" data-group-count="{n} addresses" data-too-many-results="{n} results found. Enter more of the address to improve results" data-error-api="Sorry, there was a problem loading addresses. We are working to fix the problem. Please try again later.">
        <input type="text" id="address-lookup" class="input input--text input-type__input js-autosuggest-input " autocomplete="off" />
        <div class="autosuggest-input__results js-autosuggest-results">
          <header class="autosuggest-input__results-title u-fs-s">Select an address</header>
          <ul class="autosuggest-input__listbox js-autosuggest-listbox" role="listbox" id="address-lookup-listbox" aria-labelledby="address-lookup-label" tabindex="-1"></ul>
        </div>
        <div class="autosuggest-input__instructions u-vh js-autosuggest-instructions" id="address-lookup-instructions" tabindex="-1">Use up and down keys to navigate suggestions once you&#39;ve typed more than two characters. Use the enter key to select a suggestion. Touch device users, explore by touch or with swipe gestures.</div>
        <div class="autosuggest-input__status u-vh js-autosuggest-aria-status" aria-live="assertive" role="status" tabindex="-1"></div>
      </div>
    </div>
  </div>
</div>
Nunjucks macro options
Name Type Required Description
autosuggestData string true URL of the JSON file with the autosuggest data that needs to be searched
APIDomain string false Set an api domain when using an external API to suggest results
APIDomainBearerToken string false Set a bearer token for api authorization on the AIMS address api. Defaults to basic auth
allowMultiple boolean false Allows the component to accept multiple selections
instructions string true Instructions on how to use the autosuggest that will be read out by screenreaders
ariaYouHaveSelected string true Aria message to tell the user that they have selected an answer
ariaMinChars string true Aria message to tell the user how many charecters they need to enter before autosuggest will start
ariaResultsLabel string true Aria message to tell the user that suggestions are available
ariaOneResult string true Aria message to tell the user there is only one suggestion left
ariaNResults string true Aria message to tell the user how many suggestions are left
ariaLimitedResults string true Aria message to tell the user if the results have been limited and what they are limited to
ariaGroupedResults string true Aria message to tell the user about a grouped result e.g There are {n} for {x}
groupCount string true Aria message to tell the user the number of addresses in a group e.g. {n} addresses
moreResults string true Aria message to tell the user to continue to type to refine suggestions
noResults string true message to tell the user there are no results
tooManyResults string true message to tell the user there are too many results to display and the user should refine the search
typeMore string true message to encourage the user to enter more characters to get suggestions
resultsTitle string true Title of results to be displayed on screen at the top of the results
errorTitle string false Error message title displayed in the error panel
errorMessageEnter string false Error message description displayed in the error panel when the input is empty
errorMessageSelect string false Error message description displayed in the error panel when a suggestion has not been selected
errorMessageAPI string false Error message displayed when the API has failed during a search
errorMessageAPILinkText string false Link text used to toggle to a manual mode when using the address macro
isEditable boolean false Used with the address macro to invoke population of manual fields upon selection of suggestion
options Object<Options> false Option to provide key value pairs that will be added as data attributes to the component that will be added as parameters to the address index api
mandatory boolean false Set the autosuggest input to be mandatory and use client side validation for empty form submission

Options

Name Type Required Description
regionCode string false Sets the provided region code e.g. en-gb
adressType string false Sets the provided address type e.g. resedential
oneYearAgo string false If “true” will set a query parameter of epoch=75 
{% from "components/input/_macro.njk" import onsInput %}
<div class="grid grid--gutterless">
    <div class="grid__col col-8@m js-address-autosuggest">
        {{ onsInput({
            "id": "address-lookup",
            "label": {
                "text": "Enter address or postcode and select from results",
                "id": "address-lookup-label",
                "classes": "js-autosuggest-label"
            },
            "autocomplete": "off",
            "autosuggest":{
                "classes": "js-address-not-editable",
                "instructions": "Use up and down keys to navigate suggestions once you\'ve typed more than two characters. Use the enter key to select a suggestion. Touch device users, explore by touch or with swipe gestures.",
                "ariaYouHaveSelected": "You have selected",
                "ariaMinChars": "Enter 3 or more characters for suggestions.",
                "ariaResultsLabel": "Address suggestions",
                "ariaOneResult": "There is one suggestion available.",
                "ariaNResults": "There are {n} suggestions available.",
                "ariaLimitedResults": "Results have been limited to 10 suggestions. Type more characters to improve your search",
                "ariaGroupedResults": "There are {n} addresses for {x}",
                "groupCount": "{n} addresses",
                "moreResults": "Enter more of the address to improve results",
                "resultsTitle": "Select an address",
                "noResults": "No results found. Try entering a different part of the address",
                "typeMore": "Enter more of the address to get results",
                "tooManyResults": "{n} results found. Enter more of the address to improve results",
                "externalInitialiser": true,
                "APIDomain": "https://whitelodge-ai-api.census-gcp.onsdigital.uk",
                "errorTitle": "There is a problem with your answer",
                "errorMessageEnter": "Enter an address",
                "errorMessageSelect": "Select an address",
                "errorMessageAPI": "Sorry, there was a problem loading addresses. We are working to fix the problem. Please try again later."
            }
        }) }}
    </div>
</div>

Research on this component

If you have conducted any user research using this component, please feed back your findings via the Design System forum 

Design System forum

Discuss ‘Autosuggest’ on GitHub 

More in ‘Components’