Accessible component patterns

Search

A search field as a combobox: results appear as you type, arrow keys move through them, and without JavaScript the form leads to the site map.

Component
<ad-search>
APG pattern
Combobox with Listbox Popup
WCAG criteria
  • 1.3.1 Info and Relationships
  • 2.1.1 Keyboard
  • 2.4.5 Multiple Ways
  • 3.3.2 Labels or Instructions
  • 4.1.2 Name, Role, Value
  • 4.1.3 Status Messages

Demo

The search in the header is the live demo. Type “accessibility”, for example, and move through the results with the arrow keys.

Why it is accessible

The search in the header is a plain form with a label and a button. With JavaScript, the field becomes a combobox following the APG pattern: the list of results has the role listbox, the currently highlighted result is linked via aria-activedescendant, so focus stays in the field and you can keep typing. A status line such as “12 results” is read out automatically by a screen reader.

Search runs against an index generated when the website is built (Pagefind), directly in the browser and without sending any data to a server. The index loads only on the first click into the field. Diacritics aren't required: typing without them still matches accented results.

Test it yourself

Keyboard

  • Tab into the field in the header and type “accessibility”.
  • ↓ and ↑ move through the results, Enter opens the highlighted one, and Escape closes the list.
  • Enter with no result highlighted opens the search page with every result.

Screen reader

  • After typing a term you hear the number of results; moving with the arrow keys, you hear the name and excerpt of each result.

Zoom and reflow

  • The results list has a limited height and scrolls; at a width of 320px it takes up the full width of the screen.

Without JavaScript

The form submits to the site map, which lists every page and notes that search needs JavaScript. The search term stays in the address.

Code to copy

<ad-search data-lang="en" data-search-page="/en/search/" data-strings='{ "results": { "one": "{n} result", "other": "{n} results" } }'>
  <form role="search" method="get" action="/en/sitemap/">
    <label for="q">Search this website</label>
    <input id="q" name="q" type="search" autocomplete="off">
    <button type="submit">Search</button>
  </form>
</ad-search>
<link rel="stylesheet" href="/assets/js/components/ad-search/ad-search.css">
<script type="module" src="/assets/js/components/ad-search/ad-search.js"></script>