Skip to content
  • Delivery

How to prototype — An accessible autocomplete

by Alex Torrance

A practical step by step guide for how to use the accessible autocomplete component in the GOV.UK prototype kit.

As part of our design process, we use prototyping to communicate and test our assumptions. Prototypes can be created in many forms appropriate to the context; including paper, conversations and sometimes fully interactive experiences designed in code. 

Prototyping in code is incredibly useful for helping teams understand the success of end-to-end task flows, the comprehension of content in context, and the usability of micro-interactions. Prototyping also serves as a valuable bridge to development, facilitating deeper conversations about technology rather than just design.

Prototyping should always be rapid relative to the context. However, there are repeatable occasions where teams have to create a prototype that’s complex and challenging. Our interaction and product design team have created guides to help each other overcome these challenges and work more efficiently. Today, we want to start sharing these guides publicly so they can help the wider design community and digital teams too. 

In this first one, I've written this step by step guide on how to use the accessible autocomplete component in the GOV.UK prototype kit. There aren’t any instructions included with the code for using with the prototype kit, and it’s not straightforward if you’re not familiar with javascript.

Often users have to choose an item from a list of available options. We know there are usability and accessibility issues with using the browser’s built-in select dropdowns, especially when choosing from a large list of options. Autocompletes are a good alternative to use when the user knows what they want to choose (for example, choosing their country of birth).

I've created an example repo you can download to check the code.


Download the accessible autocomplete code, you can download the zip or clone the repo if you prefer to use git.

Copy the files to your prototype

Copy the minified files from the /dist folder to your prototype.

Copy accessible-autocomplete.min.js to app/assets/javascripts (you can also copy if you want to keep the source map for debugging.

Copy accessible-autocomplete.min.css to app/assets/css (you will need to create this folder).

Include the javascript and CSS

Include the javascript file in app/views/layouts/main.html 

Add the following code to the end of the file:


{% block scripts %}

  {{ super() }}

  <script src="/public/javascripts/accessible-autocomplete.min.js"></script>

{% endblock %}


Include the CSS file in app/views/layouts/main.html


Add the following code to the end of the file:


{% block stylesheets %}

  {{ super() }}

  <link href="/public/css/accessible-autocomplete.min.css" rel="stylesheet" type="text/css" />

{% endblock %}


You will also need to add some styles to fix the font for the autocomplete input and results. Add this to the end of app/assets/sass/application.scss:


.autocomplete__wrapper * {

  @include govuk-typography-common();


Set up your select tag

Enhancing a select tag is probably the easiest way to get the autocomplete set up in the prototype kit. You can put the data right in the view, rather than importing it using client side javascript. Using progressive enhancement also means it’s available to users when javascript is unavailable.

In our example we have a select tag showing a list of countries and territories. It has 278 options – obviously too many for a dropdown to be easy to use.


<select class="govuk-select" name="choose-country" id="choose-country">

  <option value="territory:AE-AZ">Abu Dhabi</option>

  <option value="country:AF">Afghanistan</option>

  <option value="territory:AE-AJ">Ajman</option>

  <option value="territory:XQZ">Akrotiri</option>

  <option value="country:AL">Albania</option>


  <option value="country:ZM">Zambia</option>

  <option value="country:ZW">Zimbabwe</option>

  <option value="territory:AX">Åland Islands</option>



To turn the select into an autocomplete we need to add the following javascript to app/assets/javascripts/application.js inside the window.GOVUKPrototypeKit.documentReady(() => { ... } block:


let selectElement = document.querySelector('#choose-country')



  defaultValue: '',

  selectElement: selectElement



You should change the id inside the querySelector function to match the id of your select tag.

You should now be able to search the options using the autocomplete.

Set up synonym searching

Often when using autocomplete you want to allow users to search for a result using a synonym.

In the following example we’ll add some javascript to use the values from the select’s option tags as synonyms. 

Add the source option to the autocomplete code in app/assets/javascripts/application.js:


let selectElement = document.querySelector('#choose-country')



  defaultValue: '',

  source: (query, populateResults) => {

    const options = selectElement.querySelectorAll('option')

    let results = []



      (opt, i, list) => {

        let queryRegExp = new RegExp(query.trim(), 'i')

        let value = opt.getAttribute('value')

        let text = opt.innerText.trim()

        if (queryRegExp.test(value) || queryRegExp.test(text)) {








  selectElement: selectElement



You should now be able to search using the country codes. Try typing “gb” or “az” and see which results appear.

Next steps

You could further adapt this code to use a data attribute attached to the options, and could populate this with multiple synonyms, separated by a delimiter.

Join us

If you’re interested in being part of a design team that works on exciting challenges to make a real difference in the world, and creates time to support each other and the community with guides like this, we’re hiring!

Check out our current career openings for interaction and product designers as well as other opportunities.

Alex Torrance's avatar

Alex Torrance

Design Lead

Contact Alex

Our recent design blog posts

Transformation is for everyone. We love sharing our thoughts, approaches, learning and research all gained from the work we do.

Content Designer First Alpha

So, you’re on your first alpha? A content designer’s story…

Tim takes us through his experiences as a content designer working on his first alpha.

“This is how we do it” – Design Research

A look at our approach to Design Research at TPXimpact, and some of the projects our team has been working on

Our approach to co-design

We share our overall approach to co-design, what it is and isn’t, and why and when we use it