Back to projects
Projectintermediate 7 steps ~90 min

Accessible Autocomplete

Build the autocomplete every product needs, the way design system teams do: tested ranking that ignores case and accents, highlighted matches, the full ARIA combobox pattern, and async search with debounce, cancellation, caching, and every state.

What you'll build

An autocomplete that works with a keyboard and a screen reader, never shows stale results, and sends one request per pause.

  • React
  • ARIA combobox
  • debounce
  • AbortController
  • Unicode normalization
Project briefrequirements and design decisions

Requirements

  • Results ranked: prefix matches, then word matches, then anything containing the text
  • Case- and accent-insensitive: "cote" finds Côte d'Ivoire
  • Full keyboard support: arrows, Enter, Escape
  • Screen readers announce the result count and the highlighted option
  • The newest query always wins, even on a slow network

Architecture decisions

  • Ranking and highlighting are pure functions in their own module
  • Focus stays in the input; aria-activedescendant points at the active option
  • One effect cleanup cancels both the debounce timer and the in-flight request
  • Results cached per query, so going back is instant

Stretch goals

  • Recent searches when the input is empty
  • Typo tolerance and aliases ("USA", "UK")
  • Multi-select tags
  • @mentions in a textarea

Production checklist

  • IME composition handling (isComposing)
  • Server-side ranking with popularity
  • Analytics on picked position and abandoned searches
  • Tests with VoiceOver and NVDA

1What we're building

"Build an autocomplete" is one of the most common frontend interview questions, and one of the most common components in real products: search boxes, address forms, tag pickers, @mentions. It's also one of the most often broken. A list of divs under an input looks right, but it's unusable with a keyboard, silent to screen readers, and full of race conditions.

You'll build a country picker the way a design system team would:

  • Ranking that puts the best matches first and ignores case and accents ("cote" finds Côte d'Ivoire)
  • Highlighted matching text
  • The full ARIA combobox pattern: arrow keys, Enter, Escape, and a screen reader experience that announces results and the highlighted option
  • Async search against a mock service, with debouncing, cancellation (the newest query always wins), caching, and loading, empty, and error states
1countries.js sample data 2search.js normalize, rankMatches, highlight (pure, tested) 3api.js a pretend search service with slow and outage switches 4useAutocomplete.js debounce, cancel, cache, status 5Combobox.jsx the accessible combobox 6App.jsx a shipping form that uses it

What you'll learn: search ranking, Unicode normalization, the combobox pattern from the WAI-ARIA Authoring Practices, aria-activedescendant, live regions, and how a single effect cleanup handles both debouncing and race conditions.

Accessible Autocomplete project | Bloom