combobox-autocomplete
Skill0 starsChanged 29 days agoMITView on GitHub
Use when a search or autocomplete field cannot be driven with the arrow keys, when a label is missing or replaced by a placeholder, or when a screen reader cannot say how many suggestions are showing.
In this repository33 other files it gives its agents.
- AGENTS.mdAGENTS.md
- accessible-authenticationSkill
- accessible-formsSkill
- accessible-nameSkill
- accordion-disclosureSkill
- audit-componentSkill
- carouselSkill
- charts-and-datavizSkill
- data-tableSkill
- email-html-accessibilitySkill
- fix-color-contrastSkill
- forced-colors-and-dark-modeSkill
- headings-and-landmarksSkill
- keyboard-focusSkill
- live-regionsSkill
- media-captionsSkill
- menu-buttonSkill
- modal-dialogSkill
- motion-and-animationSkill
- page-title-and-languageSkill
- pagination-and-searchSkill
- pointer-and-gesturesSkill
- predictable-contextSkill
- progress-and-loadingSkill
- screen-reader-test-planSkill
- semantic-htmlSkill
- skip-linksSkill
- svg-and-iconsSkill
- tabsSkill
- tooltip-popoverSkill
- triage-automated-resultsSkill
- wcag22-new-criteriaSkill
- zoom-reflow-text-spacingSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 68
Track the active option with
aria-activedescendant: Keep DOM focus in the input at all times and point aria-activedescendant at the id of …
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Combobox and autocomplete
Criteria: SC 2.1.1 Keyboard, SC 4.1.2 Name, Role, Value, SC 1.3.5 Identify Input Purpose, SC 3.3.2 Labels or Instructions
A combobox is an input paired with a popup list. Reach for the simplest control
that does the job: <select> for a short fixed list, and
<input list="…"> with a <datalist> for free text with suggestions. Only build
the WAI-ARIA Authoring Practices
Combobox pattern when you
need live filtering, rich option markup, or a list driven by a server. The
mistake that matters most is a hand-rolled combobox whose options are unreachable
from the keyboard.
When to use
- "I can type in the field but the Down Arrow does nothing."
- "The suggestions appear but the screen reader never mentions them."
- "The field has no label, only grey placeholder text."
- Building or reviewing anything with
role="combobox"oraria-autocomplete.
Procedure
Choose the least custom control that fits.
Situation Use Short, known, fixed list <select>Free text with a hint list <input list="…">+<datalist>Live filtering, rich options, remote data ARIA combobox (the rest of this skill) <datalist>is announced and keyboard-navigable by the platform, so it clears SC 2.1.1 and SC 4.1.2 without ARIA. Do not rebuild it with arole="listbox"just to style the options if the platform version is enough.Label the field, and state the expected value. An explicit
<label for>gives SC 3.3.2 its instruction and SC 4.1.2 its name. A placeholder is neither: it disappears on the first keystroke and assistive technology may not expose it.<!-- Fails SC 4.1.2 and SC 3.3.2 — placeholder only, no label, no instruction --> <input placeholder="Country"> <!-- Passes — explicit label, programmatic input purpose, stated expectation --> <label for="country">Country (start typing to filter the list)</label> <input id="country" name="country" autocomplete="country-name" role="combobox" aria-expanded="false" aria-controls="country-list" aria-autocomplete="list"> <ul id="country-list" role="listbox" aria-label="Countries" hidden>…</ul>- Name the field's purpose with
autocompletewhere it collects user data. SC 1.3.5 applies to inputs that gather information about the user — name, address, email, telephone, country, and similar. Map the field to the token the specification defines (name,email,tel,street-address,country-name,postal-code, …). A search box has no such purpose, soautocomplete="off"on it is harmless; on an identity field it is a failure of SC 1.3.5 and it breaks password managers and browser autofill. - Wire the relationship between input and listbox.
role="combobox"goes on the input, not on a wrapper and not on the list.aria-controlsreferences the listbox id;aria-expandedreflects whether the popup is showing. - Track the active option with
aria-activedescendant. Keep DOM focus in the input at all times and pointaria-activedescendantat the id of the option the user is on. Every option needs a stable id, and the reference must be removed or repointed the moment that option leaves the DOM (SC 4.1.2). Implement the APG keyboard model, and never trap Tab.
input.addEventListener('keydown', (e) => { if (e.key === 'ArrowDown') { e.preventDefault(); open(); moveActive(1); } else if (e.key === 'ArrowUp') { e.preventDefault(); open(); moveActive(-1); } else if (e.key === 'Enter' && activeOption) { e.preventDefault(); choose(activeOption); } else if (e.key === 'Escape' && expanded) { close(); } // keep the typed text else if (e.key === 'Tab') { close(); } // SC 2.1.1 / SC 2.1.2: let Tab through });Home and End move within the input text.
Escapecloses the popup and leaves the typed value alone; Tab closes the popup and moves on to the next control.- Announce the result count in a live region so a screen reader user knows
the list changed without moving focus (
SC 4.1.3 Status Messages). Setting the count only in the visible options is not enough for someone typing with the popup collapsed in their reading flow.
Verify
Keyboard only, in this order:
| Do this | Passing looks like | Criterion |
| Tab to the field | focus lands on the input and its label is announced | 2.1.1, 3.3.2 |
| Type a few characters | the popup opens and aria-expanded becomes "true" | 4.1.2 |
| Press Down then Up | the active option moves and is announced | 2.1.1 |
| Press Enter on an option | it is chosen and the popup closes | 2.1.1 |
| Press Escape | the popup closes and focus stays in the input | 2.1.1 |
| Press Tab with the popup open | the popup closes and focus moves to the next control | 2.1.2 |
| Read the field with a screen reader | it reports a combobox with a name and its list relationship | 4.1.2 |
| Inspect an identity field | autocomplete carries the matching token | 1.3.5 |
Assert the wiring; whether the announcement is intelligible is a judgement call.
const input = document.getElementById('country');
const list = document.getElementById('country-list');
console.assert(input.getAttribute('role') === 'combobox', 'SC 4.1.2: role is not on the input');
console.assert(input.getAttribute('aria-controls') === list.id, 'SC 4.1.2: aria-controls does not resolve');
const active = input.getAttribute('aria-activedescendant');
console.assert(!active || document.getElementById(active), 'SC 4.1.2: active option id is dangling');Failure modes
role="combobox"on the wrapper or the listbox instead of the input. The screen reader reports a combobox with no editable text, or a listbox, and the typing interaction is unannounced (SC 4.1.2).aria-expandedleft"false", or never present. The popup opens visually while assistive technology is told nothing changed, and there is no way to know a list appeared (SC 4.1.2).- A dangling
aria-activedescendant. The option was filtered out of the DOM and the reference was not repointed, so the announcement goes silent mid-typing and an idref points at nothing. - Tab trapped inside the popup. The list is a focus trap, or it only closes on Escape. Tab must close the popup and move to the next control (SC 2.1.1, SC 2.1.2).
autocomplete="off"on a name, address, or email field. This is a common way to stop the browser's own autofill dropdown from covering a custom one, and it trades a cosmetic clash for a SC 1.3.5 failure and broken password managers.- The placeholder is the label. Grey text inside the field is not a name: SC 4.1.2 has nothing to announce, and SC 3.3.2 gives no instruction once typing starts.
- Options made focusable instead of using
aria-activedescendant. Puttingtabindexon each<li>pulls focus out of the input, so the user can no longer type, and the keystrokes go to the wrong place (SC 2.1.1).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

