Autocomplete

Type “Lon” in a travel app and London Heathrow appears. Type the first letters of your street at checkout and the full address is offered. Type “@gm” in an email field and “gmail.com” is filled in. That’s autocompleteAutocompleteSuggestions shown under a field while typing, which the user can pick to finish the input.Open in glossary →: a text field that guesses what you mean while you type.

It feels simple, but it’s a text field, a dropdown and a small search engine glued together, with a network request on every pause. Bugs hide in the glue: what’s typed vs what’s selected, which response arrives last, which keys do what. This page is about the autocomplete field. The search results page behind a search bar and the timing of search requests in general are covered in Search, filters & sorting.

What is autocomplete?

An autocomplete field is a text input that shows matching suggestions as you type, so you can pick one instead of typing it all. In code (on the web and in accessibility specs) it’s called a combobox: a combination of an editable box and a list of options.

There are two important questions for every autocomplete, and testers should know the answer before starting:

• Must the user pick from the list, or is free text allowed? A city for delivery, an airport, a country or a product variant must be one of the options (it has an id behind it). A search query, a tag or a town that might not be in the list can be anything.
• Where do suggestions come from? A local list (200 countries, built into the app) is instant. A server search (millions of addresses) is slow, can fail, and answers in an unpredictable order.

Anatomy

List, inline, or both

Style	What happens	Typical use
List	A list of matching options opens under the field	Cities, addresses, products, people
Inline	The rest of the word is filled in and selected; typing on replaces it	Browser address bar, email domains
List + inline	The list opens and the first match is also completed in the field	Some address bars and code editors

Dev note

In ARIA terms these are aria-autocomplete="list", "inline" and "both". You’ll see these values in DevToolsDevToolsDeveloper tools built into browsers for inspecting pages, network traffic and errors.Open in glossary → when you inspect the field.

How it differs from similar components

Component	You type…	You get…
Autocomplete / combo box	Part of a name	Suggestions; one becomes the value (or free text)
Dropdown / select	Nothing (or one letter to jump)	One option from a fixed list
Search bar	A query	A results page; suggestions are only shortcuts
Chips / token field	Part of a name, many times	Several selected values shown as chips
Browser autofill	Nothing	Saved personal data filled into a form (see Text field)

Designs & variants

Every field here works. Type a few letters (try nis, sabac or novi), use the arrow keys, Enter and Esc, then click outside.

City

Form value: null

City

Type 2 letters to see suggestions

Form value: null

City

• Nova Pazova22330, Serbia
• Nova Varoš31320, Serbia
• Novi Bečej21220, Serbia
• Novi Kneževac23330, Serbia

qwertyuiop

Email

Type anna@g. Press → or Tab to accept, keep typing to overrule, Backspace to drop the suggestion.

Town or village

Form value: null

How a good autocomplete behaves

It waits for enough input. One letter matches half the list and wastes a server call. Most fields start after 2–3 characters (local lists can start at 1) and say so: “Type at least 2 letters”.

It waits for a pause, and ignores old answers. Requests are sent after a short debounceDebounceWaiting until the user stops typing for a moment before reacting, for example before searching.Open in glossary → (around 200–300 ms). Responses can arrive in any order, so the app must only show the answer to the latest query. Otherwise the slow answer for “no” overwrites the fast answer for “novi”: a race conditionRace conditionA bug that depends on the timing or order of events, so it only happens sometimes.Open in glossary →. The Search, filters & sorting page shows this with a live demo.

It matches the way people type. Case and accents are ignored (diacriticsDiacriticsAccent marks on letters, like é, ü, č or ž. Search usually should ignore them.Open in glossary →: “sabac” finds Šabac), and words in the middle count (“sad” finds Novi Sad). The Dropdown page has a matching lab for this.

It highlights the matched part, using the same matching rules. If the search ignores accents but the highlighting doesn’t, users see options with nothing bold and wonder why they’re there.

It shows the empty and the loading state. “No cities match ‘nobi’. Check the spelling.” is an empty stateEmpty stateThe screen a user sees when there is no content yet, like an empty cart or no search results.Open in glossary →; a spinner or “Searching…” covers slow networks. Silence (no list at all) looks like a broken field.

It keeps typed text and selected value apart. The text in the field is just text until the user chooses an option. If they edit the text afterwards, the selection must be cleared. And if they leave the field without choosing, a must-pick field shows an error (or accepts an exact match), but never saves “novi” as a city.

It obeys the keyboard. Arrows move through the options, Enter chooses, Esc closes the list (a second Esc may clear the field), Tab moves on. More in Accessibility.

It closes when it should: after choosing, on Esc, when focus leaves the field, and when the user taps outside.

When to use it

Autocomplete is a good choice when:

• The list is long (cities, airports, addresses, medicines, products), too long to scroll in a dropdown.
• Users know what they want and can type the first letters.
• Typing it fully is error-prone: long names, accents, exact spellings needed for delivery.
• You want to suggest but still allow free text (search queries, tags, small towns).

Good and bad uses

Also skip autocomplete when users need to compare options (show a list with details), and be careful with it for sensitive data: suggestions based on other users’ searches can leak private information.

Common bugs

#	Bug	What you see	Typical severity
1	Typed text saved, nothing chosen	“novi” is saved as the city; no postcode, no id	High
2	Stale results	The list shows results for an older query	Medium–High
3	No keyboard support	Arrows do nothing; Enter submits the form	High (for affected users)
4	Esc clears the field	Instead of closing the list, Esc wipes what you typed	Medium
5	List won’t close	It stays open after Tab or a tap outside and covers the form	Medium
6	Edited after choosing	Change “Novi Sad” to “Novi Pazar” by typing: the old id is still sent	High
7	Accents and case	“sabac” finds nothing, or finds Šabac but highlights nothing	Medium
8	No empty or loading state	Nothing appears, so users think the field is broken	Medium
9	Request on every keystroke	Ten requests for ten letters; flicker and rate limits	Medium
10	Hidden by the keyboard	On a phone, the list opens behind the on-screen keyboard	High
11	Silent for screen readers	No result count, options not announced	High (for affected users)
12	Special characters	&, ' or % break the request (“O’Hare”, “Ivo & Co”)	Medium

Stress-test it

Timing and matching are where autocomplete breaks. This lab answers short queries slowly, like a real server searching more rows. Use the auto-type buttons to type fast, then change one setting at a time.

🧪 Autocomplete lab

Short queries answer slowly here (like a real server searching more rows). Use the auto-type buttons to type fast, then change the settings and type again.

Minimum characters

123

Matching

Starts with (strict)Any word, ignore accents

Highlighting

NoneNaiveAccent-aware

Debounce

Off300 ms

Late responses

Show whatever arrivesIgnore stale

Debounce and late responses only matter while typing: use the auto-type buttons.

City

• Šabac15000
• Novi Sad21000

type “novi”type “nis”type “sabac”type “nóvi”type “kra”

Field text / form value

“sa” · no city selected

Screen reader hears

“2 results available.”

Requests · 0 keystrokes, 0 requests

Clear

• Type or use an auto-type button…

Naive highlighting compares raw letters, so options found through accents (Šabac for "sa", Niš for "nis") get no bold part, or the wrong one.

Nothing is selected yet. If the user leaves the field now, the form must not treat the typed text as a valid city.

Find the bug

FreshBasket’s checkout asks for a delivery address. The City field is an autocomplete with six bugs. Explore it like a real tester:

• Type a city quickly (e.g. novi) and watch the list and the network log.
• Type a city without accents (sabac, cacak) and with one the city doesn’t have (nóvi). Look at the bold part.
• Use only the keyboard: arrows, Enter, Esc, Tab.
• Click or Tab away while the list is open.
• Type part of a city and press Continue to payment without choosing.

🐞 Bug hunt: FreshBasket delivery address

This demo has 6 hidden bugs. Explore it like a tester, then check your findings.

Found0/6

shop.example.com

FreshBasketCheckout · 1 of 3

Where should we deliver?

Full name

Street and number

City

Postcode

Continue to payment

Network log Restart

• Type a city to see requests…

1. 1

   Hint: Type "novi", don't pick anything, and press Continue to payment. Read the network log.

   Typed text is saved without choosing a city

   The form sends {"city":"novi","cityId":null,"postcode":""} and the server answers 201. The confirmation shows an address with no postcode in a city that doesn't exist. Expected: a must-pick field accepts only a chosen option (or an exact match like "Novi Sad"), otherwise shows "Choose a city from the list" and blocks Continue.

   Reveal answer✓ I found this
2. 2

   Hint: Type "kra" and press the Down arrow, then Enter.

   Arrow keys don't move through the options

   Nothing gets highlighted, and Enter submits the whole form with the half-typed city. Keyboard and screen reader users can't choose a city at all. Expected (ARIA combobox pattern): Down/Up move the active option (aria-activedescendant), Enter chooses it, the list closes.

   Reveal answer✓ I found this
3. 3

   Hint: Type "novi" quickly (or paste "no" and then type "vi"). Compare the list with the field and the order of responses in the log.

   Results for an older query overwrite the current one

   Every keystroke sends a request, and shorter queries answer slower. The response for "no" arrives last and replaces the results for "novi", so Nova Varoš and Nova Pazova appear for "novi". Expected: debounce the input and ignore responses that don't belong to the latest query.

   Reveal answer✓ I found this
4. 4

   Hint: Type "subo" so the list opens, then press Esc.

   Esc clears the field instead of closing the list

   Everything you typed disappears. Users press Esc to get the list out of the way, not to start again. Expected: the first Esc only closes the list and keeps the text; clearing is a separate action (the × button, or a second Esc).

   Reveal answer✓ I found this
5. 5

   Hint: Type "kr", then click the Full name field or press Tab.

   The list doesn't close when you leave the field

   The suggestion list stays open on top of the form, covering the Postcode field and the Continue button. Expected: the list closes on blur, on a tap outside, after choosing and on Esc.

   Reveal answer✓ I found this
6. 6

   Hint: Type "sabac" and "cacak", then "nóvi". Then type "kra" and compare.

   Highlighting breaks with accents

   The search ignores accents, so Šabac, Čačak and Novi Sad are found, but none of them gets a bold part, while "kra" highlights Kraljevo correctly. The highlighter compares raw letters ("s" ≠ "š", "ó" ≠ "o"). Expected: highlighting uses the same accent-insensitive matching as the search.

   Reveal answer✓ I found this

How to test it

Checklist

Autocomplete test checklist

0 of 14 checked

Copy

• Suggestions start after the agreed number of characters, and the field says so
• Matching ignores case and accents and finds words in the middle (spec permitting)
• The matched part is highlighted correctly, also for names with accents
• Typing fast never shows results for an older query (debounce + stale responses ignored)
• Loading, no-results and error states are shown (try a typo, Slow 4G, offline)
• Choosing an option (tap, click, Enter) fills the field and related fields, and closes the list
• Must-pick fields: leaving with unmatched text shows an error; the form never saves text without an option
• Editing the text after choosing clears the old selection (and related fields)
• Free-text fields: what the user typed can be kept exactly
• Keyboard: Down/Up move, Enter chooses, Esc closes (keeps the text), Tab moves on
• The list closes on blur and on a tap outside, and is never cut off or hidden by the keyboard
• Screen readers announce the field as a combo box, the result count and the active option
• Special characters (&, ', %, emoji) and very long input don't break the request or the layout
• Re-opening the form (edit address, Back) shows the chosen option, not the half-typed text

Example test cases

Accessibility

Autocomplete is one of the hardest components to make accessible, and custom ones often fail. Check these (the ARIAARIAHTML attributes that tell assistive technology what custom elements are and what state they're in.Open in glossary → combobox pattern):

Key	What it should do
↓ / ↑	Open the list / move the active option
Enter	Choose the active option and close the list
Esc	Close the list (keep the text); a second Esc may clear
Tab	Leave the field (and close the list)

• The active option is announced: focus stays in the input (so typing still works) while the screen reader reads “Novi Pazar, 2 of 4”.
  Dev note: Roles and states

  The input has role="combobox", aria-expanded, aria-controls (pointing to the list) and aria-autocomplete. The list has role="listbox", each option role="option". The active option is announced via aria-activedescendant.
• Result count: a polite live region says “4 results available” or “No results” after typing stops. Without it, screen readerScreen readerSoftware that reads the screen aloud for blind and low-vision users, like VoiceOver or TalkBack.Open in glossary → users don’t know a list appeared.
• Visible focus on the field and a clear style for the active option, different from hover. Text 4.5:1, the active-option background and field border 3:1 (WCAG 1.4.3 / 1.4.11).
• Touch targetsTouch targetThe area of the screen that responds to a tap, which should be large enough for a finger.Open in glossary →: options at least 44×44 pt on iOS and 48×48 dp on Android. On the web, WCAG 2.5.8 (AA) asks for at least 24×24 CSS px; 44×44 px (2.5.5, AAA) is the comfortable target.
• No surprise changes: suggestions must not move focus or submit the form on their own (WCAG 3.2.2 On Input, Level A).
• Zoom and small screens: at 200 % zoom and 320 px width, the list fits and scrolls (WCAG 1.4.10 Reflow, Level AA).

Read more in Accessibility basics.

Mobile vs web

iOSAndroidWeb

• There’s no standard autocomplete control on iOS.
  Dev note

  Not in UIKit. Apps build one from a text field and a table, or use SwiftUI’s .searchable with .searchSuggestions.
• Test address suggestions with real addresses in different countries.
  Dev note

  Address suggestions often come from MapKit’s MKLocalSearchCompleter or a third-party places API.
• The keyboard covers half the screen: lists usually open full screen or right below a field moved to the top. Check on the smallest iPhone you support.
• Autocorrect can change what users type (“Nis” → “Mis”). Address and city fields usually turn it off.
• Test VoiceOver (is the number of results announced?) and Dynamic Type (do long names wrap or truncate?).

Dev note

Views: AutoCompleteTextView / MaterialAutoCompleteTextView, often inside a TextInputLayout (Material exposed dropdown menu). Compose: an editable ExposedDropdownMenuBox.

• The popup can open above the field when there’s no room below. Test near the bottom of the screen with the keyboard open.
• Back should close the suggestions first, then the keyboard, then the screen.
• Test TalkBack, font scale, landscape (very little room above the keyboard) and a slow network.

Dev note

Native: <input list="…"> with a <datalist>. It allows free text, needs no JavaScript, but looks and behaves differently in each browser and offers little control over matching.

• Custom components (React, Vue, UI libraries) must follow the ARIA combobox pattern; check roles and aria-activedescendant in DevToolsDevToolsDeveloper tools built into browsers for inspecting pages, network traffic and errors.Open in glossary → (Elements and Accessibility panes).
• Check the Network tab for debouncing and the order of responses; use the “Slow 4G” and “3G” presets.
• Browser autofill can pop up on top of the app’s own suggestions; check that the two never overlap.
  Dev note

  Teams often set autocomplete="off" on the combobox for that reason.
• Test in Chrome, Safari and Firefox, with zoom, and at narrow widths.

Related pages: matching with accents and long lists on Dropdown, the search field itself on Search bar, and debounce and race conditions in Search, filters & sorting.

Check your understanding

Quick quiz

0/5 answered · 0 correct

1. 1.A delivery form saves the city "novi" with no postcode. What went wrong?

   AThe server is slowBTyped text was accepted although no option was chosenCThe list was too shortDAutocorrect

2. 2.You type "novi" quickly and the list shows "Nova Varoš". What is the most likely cause?

   AA spelling mistake in the dataBA slower response for an older query arrived lastCThe highlighting is wrongDThe list is sorted incorrectly

3. 3.The suggestion list is open. What should Esc do?

   AClear the fieldBSubmit the formCClose the list and keep the textDChoose the first option

4. 4.Which attribute lets a screen reader announce the highlighted option while focus stays in the input?

   Aaria-activedescendantBaria-labelCaria-hiddenDtabindex="-1"

5. 5.Search finds Šabac for "sabac", but no letters are bold. What kind of bug is this?

   ANot a bugBHighlighting doesn't use the same accent-insensitive matching as the searchCA race conditionDA missing debounce

Key takeaways

• An autocomplete is a combobox: a text field plus a list of suggestions. Know whether it’s must-pick or free text before testing.
• The text in the field is not the value until the user chooses. Check what the form sends, especially after editing, Tab, Esc and Back.
• Debounce and ignore stale responses; test by typing fast on a slow network.
• Matching and highlighting must ignore case and accents the same way.
• Keyboard: arrows, Enter, Esc (close, keep text), Tab; the list closes on blur and outside taps; screen readers hear the result count.
• On phones, make sure the list isn’t hidden by the keyboard.