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
| Name | Type | Required | Description |
|---|---|---|---|
| autosuggestData | string | false | URL of the JSON file with the autosuggest data that needs to be searched. Required if not using the address index api |
| 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 screen readers |
| 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 characters they need to enter before autosuggest will start |
| minChars | integer | false | Minimum number of characters to run a query. Default is 3 |
| 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 |
| 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 | false | message 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 |
| 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 |
| resultsTitleId | string | true | ID for the results title. The ID is used in the results aria-labelledby to provide context for the results |
| input | Input (ref) | true | Configuration object for the input |
| language | string | false | The 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'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'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
| Name | Type | Required | Description |
|---|---|---|---|
| autosuggestData | string | false | URL of the JSON file with the autosuggest data that needs to be searched. Required if not using the address index api |
| 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 screen readers |
| 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 characters they need to enter before autosuggest will start |
| minChars | integer | false | Minimum number of characters to run a query. Default is 3 |
| 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 |
| 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 | false | message 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 |
| 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 |
| resultsTitleId | string | true | ID for the results title. The ID is used in the results aria-labelledby to provide context for the results |
| input | Input (ref) | true | Configuration object for the input |
| language | string | false | The 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'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'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)