Help users to Find an address
Find an address is a postcode lookup pattern that helps users to enter addresses so they will be recognised by DWP services.
Principles
An address lookup should:
- find the right address without making the user do unnecessary work
- allow different postcode formats without enforcing spacing or capitalisation
- make it easy to choose manual address entry at any point
- include a confirmation step (either for the address alone or as part of a Check answers page)
When to use this pattern
Use this pattern when users need to find a UK address.
When not to use this pattern
Do not ask users to enter an address if DWP already holds this information about them. Instead consider presenting it back to them (if you can do this securely) and asking them to confirm or update it.
Manual address entry using multiple text boxes or a single free text box is sometimes a better default option than an address lookup. Follow the GOV.UK guidance for manual address entry.
This pattern is designed for use with UK residential addresses. You may find that you need to adapt it (for example by changing field labels or adding more address lines) if you often ask for:
- business or organisational addresses, for example schools or care homes
- addresses outside the UK
How it works
This pattern is available as a plugin for the GOV.UK Prototype Kit, allowing you to insert the full pattern into a prototype with minimal coding. It includes pages, routes and logic for storing an address in the prototype session.
There is a working example of this pattern in the Design System example service.
An address lookup aims to quickly find a unique address while not making the user do unnecessary work.
A ‘search and select’ journey is a common way of balancing these goals and is used in several live DWP services, including the Child Maintenance Service.
User journey
- The user enters search terms: in this pattern, these are postcode and building number or name
- If there is more than one result, the service lists matching addresses
- The user chooses an address from the list
- The user checks and confirms the chosen address
Every screen includes a Back link and the option of manual address entry. Follow GOV.UK guidance for validation rules and errors on text inputs.
Search page
<div class="govuk-width-container">
<h1 class="govuk-heading-l">Find an address</h1>
<div class="govuk-form-group">
<label class="govuk-label" for="postcode">
Postcode
</label>
<div id="postcode-hint" class="govuk-hint">
For example, AA3 1AB.
</div>
<input
class="govuk-input govuk-!-width-two-thirds" id="postcode" name="postcode" type="text" aria-describedby="postcode-hint">
</div>
<div class="govuk-form-group">
<label class="govuk-label" for="searchString">
Building number or name
</label>
<div id="searchString-hint" class="govuk-hint">
For example, 15 or Prospect Cottage.
</div>
<input
class="govuk-input govuk-!-width-two-thirds" id="searchString" name="searchString" type="text" aria-describedby="searchString-hint">
</div>
<button type="submit" class="govuk-button" data-module="govuk-button">
Find address
</button>
<p class="govuk-body govuk-!-margin-bottom-0"><a href="#" class="govuk-link">Enter address manually</a></p>
</div>{% from "govuk/components/button/macro.njk" import govukButton %}
{% from "govuk/components/input/macro.njk" import govukInput %}
<div class="govuk-width-container">
<h1 class="govuk-heading-l">Find an address</h1>
{{ govukInput({
label: {
text: "Postcode"
},
classes: "govuk-!-width-two-thirds",
hint: {
text: "For example, AA3 1AB."
},
id: "postcode",
name: "postcode"
}) }}
{{ govukInput({
label: {
text: "Building number or name"
},
classes: "govuk-!-width-two-thirds",
hint: {
text: "For example, 15 or Prospect Cottage."
},
id: "searchString",
name: "searchString"
}) }}
{{ govukButton({
text: "Find address"
}) }}
<p class="govuk-body govuk-!-margin-bottom-0"><a href="#" class="govuk-link">Enter address manually</a></p>
</div>In this example both search fields are optional: the user can enter postcode, building number or both. This allows searching for addresses whose postcode the user does not know, for example a business or care home.
Users who are new to the UK may not understand what a postcode is. You may want to use hint text to give examples or explain where to find the information.
One service found that users sometimes pasted their whole address into the search field, not understanding that it was a search. Labelling the primary button on the search page ‘Find address’, not ‘Continue’ may help with this.
Search results page
<div class="govuk-width-container">
<div class="govuk-form-group">
<fieldset class="govuk-fieldset">
<legend class="govuk-fieldset__legend govuk-fieldset__legend--l">
<h1 class="govuk-fieldset__heading">
Select an address
</h1>
</legend>
<div class="govuk-radios govuk-radios--small" data-module="govuk-radios">
<p>6 addresses found for <b>wr11nl</b> and <b>1</b>. <a href='#'>Search again</a></p>
<div class="govuk-radios__item">
<input class="govuk-radios__input" id="select-an-address" name="select-an-address" type="radio" value="1 Washington Street, Worcester, WR1 1NL"
data-ga-question="Select an address" data-ga-answer="Answer 1">
<label class="govuk-label govuk-radios__label" for="select-an-address">
1 Washington Street, Worcester, WR1 1NL
</label>
</div>
<div class="govuk-radios__item">
<input class="govuk-radios__input" id="select-an-address-2" name="select-an-address" type="radio" value="10 Washington Street, Worcester, WR1 1NL"
data-ga-question="Select an address" data-ga-answer="Answer 2">
<label class="govuk-label govuk-radios__label" for="select-an-address-2">
10 Washington Street, Worcester, WR1 1NL
</label>
</div>
<div class="govuk-radios__item">
<input class="govuk-radios__input" id="select-an-address-3" name="select-an-address" type="radio" value="11 Washington Street, Worcester, WR1 1NL"
data-ga-question="Select an address" data-ga-answer="Answer 2">
<label class="govuk-label govuk-radios__label" for="select-an-address-3">
11 Washington Street, Worcester, WR1 1NL
</label>
</div>
<div class="govuk-radios__item">
<input class="govuk-radios__input" id="select-an-address-4" name="select-an-address" type="radio" value="101 Washington Street, Worcester, WR1 1NL"
data-ga-question="Select an address" data-ga-answer="Answer 3">
<label class="govuk-label govuk-radios__label" for="select-an-address-4">
101 Washington Street, Worcester, WR1 1NL
</label>
</div>
<div class="govuk-radios__item">
<input class="govuk-radios__input" id="select-an-address-5" name="select-an-address" type="radio" value="110 Washington Street, Worcester, WR1 1NL"
data-ga-question="Select an address" data-ga-answer="Answer 4">
<label class="govuk-label govuk-radios__label" for="select-an-address-5">
110 Washington Street, Worcester, WR1 1NL
</label>
</div>
<div class="govuk-radios__item">
<input class="govuk-radios__input" id="select-an-address-6" name="select-an-address" type="radio" value="111 Washington Street, Worcester, WR1 1NL"
data-ga-question="Select an address" data-ga-answer="Answer 5">
<label class="govuk-label govuk-radios__label" for="select-an-address-6">
111 Washington Street, Worcester, WR1 1NL
</label>
</div>
</div>
</fieldset>
</div>
<button type="submit" class="govuk-button" data-module="govuk-button">
Use this address
</button>
<p class="govuk-body govuk-!-margin-bottom-0"><a href="#" class="govuk-link">Enter address manually</a></p>
</div>{% from "govuk/components/button/macro.njk" import govukButton %}
{% from "govuk/components/radios/macro.njk" import govukRadios %}
<div class="govuk-width-container">
{{ govukRadios({
name: "select-an-address",
classes: "govuk-radios--small",
fieldset: {
legend: {
text: "Select an address",
isPageHeading: true,
classes: "govuk-fieldset__legend--l"
}
},
formGroup: {
beforeInputs: {
html: "<p>6 addresses found for <b>wr11nl</b> and <b>1</b>. <a href='#' >Search again</a></p>"
}
},
items: [
{
value: "1 Washington Street, Worcester, WR1 1NL",
text: "1 Washington Street, Worcester, WR1 1NL",
attributes: {
"data-ga-question": "Select an address",
"data-ga-answer": "Answer 1"
}
},
{
value: "10 Washington Street, Worcester, WR1 1NL",
text: "10 Washington Street, Worcester, WR1 1NL",
attributes: {
"data-ga-question": "Select an address",
"data-ga-answer": "Answer 2"
}
},
{
value: "11 Washington Street, Worcester, WR1 1NL",
text: "11 Washington Street, Worcester, WR1 1NL",
attributes: {
"data-ga-question": "Select an address",
"data-ga-answer": "Answer 2"
}
},
{
value: "101 Washington Street, Worcester, WR1 1NL",
text: "101 Washington Street, Worcester, WR1 1NL",
attributes: {
"data-ga-question": "Select an address",
"data-ga-answer": "Answer 3"
}
},
{
value: "110 Washington Street, Worcester, WR1 1NL",
text: "110 Washington Street, Worcester, WR1 1NL",
attributes: {
"data-ga-question": "Select an address",
"data-ga-answer": "Answer 4"
}
},
{
value: "111 Washington Street, Worcester, WR1 1NL",
text: "111 Washington Street, Worcester, WR1 1NL",
attributes: {
"data-ga-question": "Select an address",
"data-ga-answer": "Answer 5"
}
}
]
}) }}
{{ govukButton({
text: "Use this address"
}) }}
<p class="govuk-body govuk-!-margin-bottom-0"><a href="#" class="govuk-link">Enter address manually</a></p>
</div>Replay the search terms exactly as the user entered them without changing the formatting or spacing. This helps to spot and correct input errors using the ‘Search again’ link.
Some data sources will return addresses in ALL CAPITALS, which is hard to read. If your data source does this, transform results into title case before displaying them to users.
Show the matching addresses as a single list of radios, with a primary button to confirm the choice.
Avoid pagination
Do not use pagination to split up a long list of results. Pagination forces people to guess which page their result is on and also makes navigation more difficult for screen reader users.
Showing all results on the same page means people can use their browser’s Find function to find the right result in a long list.
If your research finds that long results lists are causing problems, it is better to offer a way to refine the search and make sure manual entry is easily available.
No results page
No address found
We could not find an address that matches wr11nl and 1. You can search again or enter the address manually.
<div class="govuk-width-container">
<h1 class="govuk-heading-l">No address found</h1>
<p>We could not find an address that matches <b>wr11nl</b> and <b>1</b>. You can search again or enter the address manually.</p>
<p><a href="#">Search again</a></p>
<p class="govuk-body govuk-!-margin-bottom-0"><a href="#" class="govuk-link">Enter address manually</a></p>
</div><div class="govuk-width-container">
<h1 class="govuk-heading-l">No address found</h1>
<p>We could not find an address that matches <b>wr11nl</b> and <b>1</b>. You can search again or enter the address manually.</p>
<p><a href="#">Search again</a></p>
<p class="govuk-body govuk-!-margin-bottom-0"><a href="#" class="govuk-link">Enter address manually</a></p>
</div>If the search produces no results, replay the search terms and give the option of searching again or entering the address manually.
Confirm page
Confirm address
6 addresses found for wr11nl and 1. Search again
Worcester
WR1 1NL
<div class="govuk-width-container">
<h1 class="govuk-heading-l">Confirm address</h1>
<p>6 addresses found for <b>wr11nl</b> and <b>1</b>. <a href="#">Search again</a></p>
<div class="govuk-inset-text">
1 Washington Street<br>Worcester<br>WR1 1NL
</div>
<button type="submit" class="govuk-button" data-module="govuk-button">
Use this address
</button>
<p class="govuk-body"><a href="#" class="govuk-link">Use a different address</a></p>
<p class="govuk-body govuk-!-margin-bottom-0"><a href="#" class="govuk-link">Enter address manually</a></p>
</div>{% from "govuk/components/button/macro.njk" import govukButton %}
{% from "govuk/components/inset-text/macro.njk" import govukInsetText %}
<div class="govuk-width-container">
<h1 class="govuk-heading-l">Confirm address</h1>
<p>6 addresses found for <b>wr11nl</b> and <b>1</b>. <a href="#">Search again</a></p>
{{ govukInsetText({
html: "1 Washington Street<br>Worcester<br>WR1 1NL"
}) }}
{{ govukButton({
text: "Use this address"
}) }}
<p class="govuk-body"><a href="#" class="govuk-link">Use a different address</a></p>
<p class="govuk-body govuk-!-margin-bottom-0"><a href="#" class="govuk-link">Enter address manually</a></p>
</div>Show the selected address in full and ask the user to confirm it. The links are:
- Search again: returns the user to the search page
- Use a different address: returns the user to the results list
- Enter address manually: takes the user to the manual address entry screen
Manual address entry
Use the GOV.UK pattern for manual address entry using multiple text inputs.
Technical guidance
API integration
DWP teams should use the DWP Address Service API. Contact the Address Service team for access.
Accessibility
Pay particular attention to the search results page, especially to how it works with a large number of results. Can users easily find and select the ‘Use this address’ button if it is at the end of a long list of radios?
For more about building accessible services see the DWP Accessibility Manual.
Research
This pattern has been tested with the DWP Address Service API, which uses Ordnance Survey reference data for addresses in Great Britain, Northern Ireland and the Channel Islands.
A similar pattern using radios for results has been successfully used in the Child Maintenance Service.
We expect that longer lists of radios may be harder to use than short lists, but we want more data from live services on when and how often this problem happens. Options include offering a results filter and switching to manual entry, but we recommend against using pagination.
One service found that screen reader users struggled with a paginated list of results: it was difficult to find the result they were looking for and some thought the “Next” link would move them forward in the service.
Alternative approaches
The main alternatives to showing search results as a list of radio buttons are to use a Select (dropdown) component or a typeahead.
Select (dropdown)
GOV.UK Design System guidance recommends against using the Select component except as a last resort: for this reason we do not recommend it in address lookups.
Typeahead
Typeaheads – where the address is looked up as the user types it into the search box – can remove the need for a separate search results page, potentially making the task simpler.
An accessible typeahead could be used with this pattern as a progressive enhancement. However, we need more examples of how they can be built accessibly and for users without JavaScript. If you have used typeahead we actively encourage you to share what you have learned on the GitHub discussion for this pattern.
The Office for National Statistics (ONS) has published research on a typeahead address search used for the 2021 Census. When used without JavaScript the typeahead was replaced by a postcode search and list of results.
Contribute
Thanks for help with this pattern to:
- the DWP Address Service team
- the Design System team at the Office for National Statistics
If you have used or researched this pattern, please let us know what you found so we can make it better for everyone. There is an open discussion for this pattern on GitHub where you can share anything you think might be useful.
We particularly want research on:
- options for filtering, grouping or otherwise refining long lists of results
- adaptations for international or non-residential addresses
- users’ preferences for manual entry or postcode search
- accessible typeahead solutions
Discuss Find an address on GitHub
Get in touch
If you’ve got a question, idea or suggestion email the Design System team on dwp-design-system@engineering.digital.dwp.gov.uk