# Accessibility

Address Lookup is developed to meet [WCAG 2.1 Level AA](https://www.w3.org/TR/WCAG21/). It implements the WAI-ARIA combobox pattern, works with screen readers and is fully operable by keyboard.

## Screen Reader Support[​](#screen-reader-support "Direct link to Screen Reader Support")

The suggestion list is exposed as an ARIA combobox: the input carries `role="combobox"`, `aria-expanded` and `aria-controls`, and the suggestion list is a `listbox` of `option` elements. DOM focus stays on the input at all times - the highlighted suggestion is conveyed via `aria-activedescendant`, so screen reader users hear each suggestion as they arrow through it, along with its position in the list.

By default Address Lookup uses ARIA 1.0 authoring, which has the widest screen reader support (notably VoiceOver and NVDA). The [`aria` option](/docs/address-lookup/configuration-reference.md) switches to ARIA 1.1 authoring if preferred.

A visually hidden live region announces events as they happen:

* The number of addresses found, e.g. `"10 addresses available"`
* With the first results only: the active search country and how to change it, e.g. `"Searching United States. Press Tab to change country"`
* The number of countries listed when selecting a country
* `"Country switched to United States"` after a change of country
* Confirmation that a selected address has been applied to the form
* Notices, e.g. `"No matches found"`

The `aria-label` on the suggestion list can be customised with the `msgList` option - see [Messages](/docs/address-lookup/messages.md).

## Keyboard Support[​](#keyboard-support "Direct link to Keyboard Support")

| Key                                     | Action                                                      |
| --------------------------------------- | ----------------------------------------------------------- |
| `↓` / `↑`                               | Move through suggestions, wrapping at either end            |
| `Enter`                                 | Select the highlighted suggestion and populate the form     |
| `Escape`                                | Close the suggestion list and clear the input               |
| `Home` / `End`                          | Return to the input                                         |
| `Tab`                                   | Move to the country toggle; press again to leave the widget |
| `Enter` / `Space` on the country toggle | Open the country list                                       |

Clickable elements rendered by Address Lookup (the country toggle, the [no-match action](/docs/address-lookup/no-match-action.md), the [unhide link](/docs/address-lookup/hide.md)) are focusable buttons and respond to `Enter` and `Space`.

## Testing[​](#testing "Direct link to Testing")

Every release is gated by automated axe-core WCAG A/AA scans and keyboard regression tests covering the interactions above.

If you find an accessibility issue, please [report it](https://github.com/addresszen/feedback/issues) - accessibility defects are treated as bugs.