Cookies on ons.gov.uk

Cookies are small files stored on your device when you visit a website. We use some essential cookies to make this website work.

We would like to set additional cookies to remember your settings and understand how you use the site. This helps us to improve our services.

You have accepted all additional cookies. You have rejected all additional cookies. You can change your cookie preferences at any time.

Skip to main content

Autosuggest

Overview

Autosuggest is used to suggest options to users as they enter something into an input field. A user can select one of the suggestions or enter their own answer.

Example Autosuggest Country contents

Nunjucks

{% from "components/autosuggest/_macro.njk" import onsAutosuggest %}

<div class="ons-grid ons-grid--gutterless">
    <div class="ons-grid__col ons-col-8@m">
        {{
            onsAutosuggest({
                "id": "country-of-birth-autosuggest",
                "input": {
                    "label": {
                        "text": "Current name of country",
                        "description": "Enter your own answer or select from suggestions",
                        "id": "country-of-birth-label"
                    },
                    "autocomplete": "off"
                },
                "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.",
                "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",
                "resultsTitleId": "country-of-birth-suggestions",
                "autosuggestData": "/examples/data/country-of-birth.json",
                "noResults": "No suggestions found. You can enter your own answer",
                "typeMore": "Continue entering to get suggestions"
            })
        }}
    </div>
</div>

Nunjucks macro options

NameTypeRequiredDescription
autosuggestDatastringfalseURL of the JSON file with the autosuggest data that needs to be searched. Required if not using the address index api
allowMultiplebooleanfalseAllows the component to accept multiple selections
instructionsstringtrueInstructions on how to use the autosuggest that will be read out by screen readers
ariaYouHaveSelectedstringtrueAria message to tell the user that they have selected an answer
ariaMinCharsstringtrueAria message to tell the user how many characters they need to enter before autosuggest will start
minCharsintegerfalseMinimum number of characters to run a query. Default is 3
ariaOneResultstringtrueAria message to tell the user there is only one suggestion left
ariaNResultsstringtrueAria message to tell the user how many suggestions are left
ariaLimitedResultsstringtrueAria message to tell the user if the results have been limited and what they are limited to
moreResultsstringtrueAria message to tell the user to continue to type to refine suggestions
noResultsstringtruemessage to tell the user there are no results
tooManyResultsstringfalsemessage to tell the user there are too many results to display and the user should refine the search. This is only required when using the address index api
typeMorestringtruemessage to encourage the user to enter more characters to get suggestions
resultsTitlestringtrueTitle of results to be displayed on screen at the top of the results
resultsTitleIdstringtrueID for the results title. The ID is used in the results aria-labelledby to provide context for the results
inputInput (ref)trueConfiguration object for the input
languagestringfalseThe ISO 639-1 Code will override the default language in page. Please note that only 'en', 'cy' and 'ni' is currently supported

HTML

<div class="ons-grid ons-grid--gutterless">
  <div class="ons-grid__col ons-col-8@m">
    <div id="country-of-birth-autosuggest-container" class="ons-autosuggest ons-js-autosuggest"
      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-min-chars=""
      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="/examples/data/country-of-birth.json">
      <div class="ons-field">
        <label class="ons-label ons-label--with-description" for="country-of-birth-autosuggest"
          aria-describedby="country-of-birth-label-description-hint" id="country-of-birth-label">Current name of
          country</label>
        <span id="country-of-birth-label-description-hint"
          class="ons-label__description ons-input--with-description">Enter your own answer or select from
          suggestions</span>
        <input type="text" id="country-of-birth-autosuggest"
          class="ons-input ons-input--text ons-input-type__input ons-js-autosuggest-input" autocomplete="off"
          aria-describedby="country-of-birth-label-description-hint" />
      </div>
      <div class="ons-autosuggest__results ons-js-autosuggest-results ons-input--w-20">
        <div id="country-of-birth-suggestions" class="ons-autosuggest__results-title ons-u-fs-s">Suggestions</div>
        <ul class="ons-autosuggest__listbox ons-js-autosuggest-listbox" title="Suggestions" role="listbox"
          id="country-of-birth-autosuggest-listbox" tabindex="-1"></ul>
      </div>
      <div class="ons-autosuggest__instructions ons-u-vh ons-js-autosuggest-instructions"
        id="country-of-birth-autosuggest-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="ons-autosuggest__status ons-u-vh ons-js-autosuggest-aria-status" aria-live="assertive"
        aria-atomic="true" role="status" tabindex="-1"></div>
    </div>
  </div>
</div>

When to use this component

Use the autosuggest component to help users select from a list of standard responses, for example, countries, languages or nationalities. You could also create your own list for the user to pick from.

How to use this component

The list needs to be made available as a JSON file (.json). To query the list we use a JavaScript library called Fuse.js (opens in a new tab)  . You will need to provide the URL where the JSON file is stored using the autosuggestData parameter.

List formatting

This code example shows how your JSON should be formatted. The key should be the language code that matches the lang attribute on the <html> element of the page.

[
  {
    "en": "England"
  },
  {
    "en": "Wales"
  },
  {
    "en": "Scotland"
  },
  {
    "en": "Northern Ireland"
  },
]

Multiple suggestions

You can configure the component to allow multiple suggestions by passing in the parameter allowMultiple: "true".

Example Autosuggest Country Multiple contents

Nunjucks
{% from "components/autosuggest/_macro.njk" import onsAutosuggest %}

<div class="ons-grid ons-grid--gutterless">
    <div class="ons-grid__col ons-col-8@m">
        {{
            onsAutosuggest({
                "id": "country-of-birth-autosuggest-multiple",
                "input": {
                    "label": {
                        "text": "Passport",
                        "id": "country-of-birth-label-multiple",
                        "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"
                },
                "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.",
                "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",
                "resultsTitleId": "country-of-birth-suggestions",
                "allowMultiple": true,
                "autosuggestData": "/examples/data/country-of-birth.json",
                "noResults": "No suggestions found. You can enter your own answer",
                "typeMore": "Continue entering to get suggestions",
                "language": "en"
            })
        }}
    </div>
</div>
Nunjucks macro options
NameTypeRequiredDescription
autosuggestDatastringfalseURL of the JSON file with the autosuggest data that needs to be searched. Required if not using the address index api
allowMultiplebooleanfalseAllows the component to accept multiple selections
instructionsstringtrueInstructions on how to use the autosuggest that will be read out by screen readers
ariaYouHaveSelectedstringtrueAria message to tell the user that they have selected an answer
ariaMinCharsstringtrueAria message to tell the user how many characters they need to enter before autosuggest will start
minCharsintegerfalseMinimum number of characters to run a query. Default is 3
ariaOneResultstringtrueAria message to tell the user there is only one suggestion left
ariaNResultsstringtrueAria message to tell the user how many suggestions are left
ariaLimitedResultsstringtrueAria message to tell the user if the results have been limited and what they are limited to
moreResultsstringtrueAria message to tell the user to continue to type to refine suggestions
noResultsstringtruemessage to tell the user there are no results
tooManyResultsstringfalsemessage to tell the user there are too many results to display and the user should refine the search. This is only required when using the address index api
typeMorestringtruemessage to encourage the user to enter more characters to get suggestions
resultsTitlestringtrueTitle of results to be displayed on screen at the top of the results
resultsTitleIdstringtrueID for the results title. The ID is used in the results aria-labelledby to provide context for the results
inputInput (ref)trueConfiguration object for the input
languagestringfalseThe ISO 639-1 Code will override the default language in page. Please note that only 'en', 'cy' and 'ni' is currently supported
HTML
<div class="ons-grid ons-grid--gutterless">
  <div class="ons-grid__col ons-col-8@m">
    <div id="country-of-birth-autosuggest-multiple-container" class="ons-autosuggest ons-js-autosuggest"
      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-min-chars=""
      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="/examples/data/country-of-birth.json" data-lang="en">
      <div class="ons-field">
        <label class="ons-label ons-label--with-description" for="country-of-birth-autosuggest-multiple"
          aria-describedby="country-of-birth-label-multiple-description-hint"
          id="country-of-birth-label-multiple">Passport</label>
        <span id="country-of-birth-label-multiple-description-hint"
          class="ons-label__description ons-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>
        <input type="text" id="country-of-birth-autosuggest-multiple"
          class="ons-input ons-input--text ons-input-type__input ons-js-autosuggest-input" autocomplete="off"
          aria-describedby="country-of-birth-label-multiple-description-hint" />
      </div>
      <div class="ons-autosuggest__results ons-js-autosuggest-results ons-input--w-20">
        <div id="country-of-birth-suggestions" class="ons-autosuggest__results-title ons-u-fs-s">Suggestions</div>
        <ul class="ons-autosuggest__listbox ons-js-autosuggest-listbox" title="Suggestions" role="listbox"
          id="country-of-birth-autosuggest-multiple-listbox" tabindex="-1"></ul>
      </div>
      <div class="ons-autosuggest__instructions ons-u-vh ons-js-autosuggest-instructions"
        id="country-of-birth-autosuggest-multiple-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="ons-autosuggest__status ons-u-vh ons-js-autosuggest-aria-status" aria-live="assertive"
        aria-atomic="true" role="status" tabindex="-1"></div>
    </div>
  </div>
</div>

Help improve this page

Let us know how we could improve this page, or share your user research findings. Discuss the ‘Autosuggest’ component on GitHub (opens in a new tab)