On this page
Frontend System Design — Autocomplete Widget
Last reviewed 14 Oct 2026
Part of the system design series. Uses the frontend framework. The backend is Search Autocomplete; a working implementation is in Machine Coding — Autocomplete.
1. Requirements
Clarify which kind first: search suggestions (Google-style, free text plus suggestions) or a select-from-options combobox (pick a city/user/tag).
Functional
- Show suggestions as the user types; select by mouse, touch or keyboard.
- Highlight the matched part; show recent searches when the input is empty.
- Results may come from a server, a local list, or both.
Non-functional
- Feels instant (suggestions within ~100–200 ms of a pause in typing) without flooding the server.
- Correct under slow and out-of-order network responses.
- Fully keyboard and screen-reader accessible.
- Reusable across the product: configurable data source, rendering and behaviour.
2. Component API
type AutocompleteProps<T> = { fetchSuggestions: (query: string, signal: AbortSignal) => Promise<T[]>; // or a static list renderItem?: (item: T, state: { active: boolean; query: string }) => ReactNode; getItemKey: (item: T) => string; getItemLabel: (item: T) => string; onSelect: (item: T) => void; minQueryLength?: number; // default 1 debounceMs?: number; // default ~200 maxResults?: number; // default 10 placeholder?: string; emptyState?: ReactNode; // "No results"};Keep the network out of the component’s internals by accepting fetchSuggestions — the same widget then works for users, cities, or local data, and is easy to test. For a design system, offer a headless version (state + keyboard logic as a hook) plus a default styled one.
3. Architecture and data flow
flowchart LR
IN[Input onChange] --> DB[Debounce ~200ms]
DB --> C{In cache?}
C -->|yes| R[Render results]
C -->|no| AB[Abort previous request]
AB --> F[fetchSuggestions with AbortSignal]
F --> CHK{Response for latest query?}
CHK -->|yes| W[Write cache] --> R
CHK -->|no| X[Discard]
State: query, results, status (idle | loading | success | error), activeIndex, isOpen.
4. Deep dive — network correctness and efficiency
- Debounce input (≈150–300 ms) so typing “kubernetes” sends one or two requests, not ten. (Throttling is an alternative if you want results during fast typing.)
- Race conditions: request for “kub” can return after the request for “kube”. Either abort the previous request with
AbortControllerwhen a new one starts, or tag each request with the query and ignore responses that don’t match the current input. Do both — abort saves bandwidth, the check guarantees correctness. - Cache results per normalized query (lowercased, trimmed) in an in-memory LRU with a TTL. Backspacing from “kubern” to “kube” is instant. You can also filter cached results for a longer prefix locally while the real request is in flight.
- Minimum length and empty input handling: don’t query for "" — show recent searches from
localStorageinstead. - Errors: show a quiet inline error; keep the last good results if appropriate; don’t open an alert per keystroke.
let controller: AbortController | null = null;async function search(query: string) { controller?.abort(); controller = new AbortController(); try { const items = await fetchSuggestions(query, controller.signal); if (query === latestQuery) setResults(items); } catch (e) { if ((e as Error).name !== 'AbortError') setStatus('error'); }}5. Deep dive — keyboard and accessibility
Use the WAI-ARIA combobox pattern:
- Input has
role="combobox",aria-expanded,aria-controlspointing at the listbox, andaria-activedescendantset to the active option’s id. Focus stays in the input the whole time. - The popup is
role="listbox"withrole="option"children andaria-selectedon the active one. - Keys: ↓/↑ move the active option (wrap or stop at ends), Enter selects, Escape closes (a second Escape clears), Tab moves on without hijacking, Home/End optionally.
- Announce result counts politely (“8 suggestions available”) via a live region.
- Clicking an option must not blur-close the list before the click lands — handle
mousedownwithpreventDefaultor delay the close.
6. Rendering and performance
- Highlight matched substrings by splitting the label on the query and wrapping matches in
mark— never by injecting HTML (XSS). - Cap results (10 is typical). If the list can be large (a select over 10k options), virtualize it.
- Position the popup with a positioning utility that flips above the input near the viewport bottom; on mobile, consider a full-screen search view.
- Don’t re-render the whole list on each keystroke when only
activeIndexchanges — memoize options.
7. Edge cases
- Input loses focus while a request is in flight → close and ignore the result.
- IME composition (Chinese/Japanese input) → don’t search until
compositionend. - Pasting a long string → debounce still applies; trim and cap length.
- Selecting an item fills the input — don’t trigger a new search for that exact label.
Interview follow-ups
- “User types fast, responses arrive out of order.” — Abort previous requests and check the response matches the latest query.
- “How do you reduce server load?” — Debounce, min length, client cache with TTL, server-side caching of popular prefixes.
- “How does a screen-reader user use it?” — Combobox pattern with
aria-activedescendant, listbox/option roles, live-region counts. - “How would you make this reusable across the company?” — Headless hook for logic, injectable data source and renderers, styled default.
Further reading: WAI-ARIA Authoring Practices Guide, Combobox pattern · MDN documentation on AbortController · web.dev guidance on input responsiveness (INP).