Susegad UI Accessibility GitHub

How this site looks

The view settings need JavaScript. Every page reads well without them.

Mood

The same pages, in three moods.

Theme

Components

Combobox

An input with suggestions. Without JavaScript it is the browser's own input list and datalist; with it, the ARIA APG editable combobox with a listbox popover, full keyboard support, and matching that finds places however people type them: without accents, by an older name, in another script, or spelled as heard.

quiet warm playful

Open the live demo npx @susegad/cli add combobox

Stands on: Core, Core: components, Field (TextField, TextArea, Select), Tokens

The prompt

the prompt

"Bombay", "मुंबई" and "mum" are all asking for Mumbai.

An input with suggestions. Without JavaScript it is the browser's own <input list> and <datalist>. With JavaScript it becomes the ARIA APG editable combobox, and its matching finds places however people type them.

<link rel="stylesheet" href="susegad/components/combobox/combobox.css">
<script type="module" src="susegad/components/combobox/combobox.js"></script>

<sg-combobox>
  <label for="from">Travelling from</label>
  <input id="from" name="from" list="cities" autocomplete="off">
  <datalist id="cities">
    <option value="Mumbai" data-aliases="Bombay, मुंबई">Maharashtra</option>
    <option value="Bengaluru" data-aliases="Bangalore, ಬೆಂಗಳೂರು">Karnataka</option>
  </datalist>
</sg-combobox>

The prompt

Build a combobox as a light-DOM custom element, <sg-combobox>, around a native <input list> with a visible <label> and a <datalist>, so that without JavaScript the browser's own suggestions work and the form submits whatever was typed. With JavaScript, follow the ARIA APG editable combobox with list autocomplete: remove the input's list, give it role="combobox", aria-autocomplete="list", aria-expanded and aria-controls, and build a listbox of the datalist's options as a manual popover anchored under the input with CSS anchor positioning. Keep focus in the input and move through the options with aria-activedescendant. Down Arrow opens the list and moves to the next option, Up Arrow to the previous, both wrapping; Enter chooses the active option and closes the list, or submits the form when none is active; Escape closes the list, and clears the text if it is already closed; Tab closes without choosing. Never choose for the person, and always keep what they typed. Match the way Indian place names are really typed: fold case and punctuation, strip accents from Latin letters only and leave the vowel signs of Devanagari, Kannada and other scripts alone, match the start of any word, and match aliases from data-aliases (older names and other scripts), saying "also Bombay" when an alias matched. Add a looser match for the usual romanisation variants (doubled vowels, aspirates, w for v), ranked below the exact ones. Mark the matched letters, mapping accents back to the original text. Say the number of suggestions in a polite status line once typing settles, only when it changes. Give it three registers. Quiet: a hairline box and list. Warm: write the input on the paper like the field and the select: no box, the field's pencil rule under it, inked from left to right while the input has focus and under the words away from it; a caret of two uneven pencil strokes; the list edged in ink and ruled in pencil between the suggestions, with the active suggestion's name underlined in ink by hand rather than filled. Playful: a stamped box with an off-register ghost, a caret in accent ink with a thick, round nib, and the suggestions as stamped chips. Keep the list's entrance off in quiet and under reduced motion.

Words to code

When you sayTechniqueWhat happens
without JavaScript the browser's own suggestions workprogressive enhancementThe <input list> and <datalist> are real HTML. The element reads the options from the datalist, so the no-JS path and the enhanced path share one list.
follow the ARIA APG editable combobox with list autocompleteaccessibilityThe input is the combobox and keeps focus. The listbox is controlled by it, labelled by the same label, and the active option is announced through aria-activedescendant.
a manual popover anchored under the input with CSS anchor positioningpopover API, anchorsThe list sits in the top layer, so no container clips it. anchor-name on the input and position-anchor on the list place it, with flip-block when there is no room below. Browsers without anchors get coordinates from JavaScript.
Never choose for the person, and always keep what they typedthe person decidesTyping opens the list with nothing selected. Only Enter on an active option or a click chooses. A place not in the list is kept and submitted as typed.
strip accents from Latin letters onlyUnicodeText is decomposed (NFD). A combining mark is dropped only when it follows a Latin letter, so "Balcão" folds to "balcao" while "मुंबई" keeps its anusvara and matras.
match aliases from data-aliasesaliasesEach option can list other names. A match through an alias ranks just below the same kind of match on the name, and the option says which alias matched.
a looser match for the usual romanisation variantsfoldingaa, ee and oo fold to a, i and u; th, dh, bh, kh, gh, ph and jh lose the h; w folds to v. "Tiruvanantapuram" finds Thiruvananthapuram, one rank below exact matches.
mapping accents back to the original texthighlightingEach character is folded on its own and its position remembered, so the match in the folded text maps back and the <mark> wraps "Balcão", not "Balca".
Say the number of suggestions in a polite status linelive regionA visually hidden role="status" says "2 suggestions" 450 ms after typing stops, and nothing if the number has not changed.
the field's pencil rule under it, inked while the input has focusshared drawingruleUnder() from field/rule.js: the field's graphite pencilRule() under the input, with the input's border turned transparent at the same width. On focus the ink runs the whole rule, drawn in over 560 ms; on blur it shrinks to the typed words, measured with canvas.measureText.
ruled in pencil between the suggestions … underlined in ink by handCSS masksOne hand-drawn stroke as an SVG data URI (--sg-pencil-line, vector-effect: non-scaling-stroke) is the mask for both: a ::before on each option but the last, in --sg-text-soft at 55%, and a ::after on the active option's .sg-combobox__value, in --sg-accent-text, so the underline is exactly as long as the name. The active option has no fill.
a caret of two uneven pencil strokesSVGcaret() takes a list of [d, width]; warm passes two crossing strokes of 1.9 and 1.5.

<sg-combobox> is a text input that suggests values as people type, for places, names and anything else with a known list and room for something new. It starts as the browser's own <input list> and <datalist>, and becomes the ARIA APG editable combobox when JavaScript runs.

Usage

<link rel="stylesheet" href="susegad/components/combobox/combobox.css">
<script type="module" src="susegad/components/combobox/combobox.js"></script>

<sg-combobox>
  <label for="from">Travelling from</label>
  <input id="from" name="from" list="cities" autocomplete="off" required>
  <datalist id="cities">
    <option value="Mumbai" data-aliases="Bombay, मुंबई">Maharashtra</option>
    <option value="Panaji" data-aliases="Panjim, पणजी">Goa</option>
  </datalist>
</sg-combobox>
  • The option's value is what goes into the input and the form. Its text (here the state) is shown beside it as a hint, and can be matched too.
  • data-aliases lists other names, comma-separated: an older name, a spelling people use, the name in another script.
  • Add lang to an option whose value is not English, so a screen reader pronounces it well.
  • The value is whatever the person types. The list only suggests. To insist on a listed value, validate it on the server, or with setCustomValidity() and <sg-field-note>.

Attributes, properties and events

NameKindWhat it does
registerattributequiet, warm or playful. Overrides the page's register for this element.
openpropertyWhether the suggestions are showing.
suggestionspropertyThe values on show, best first.
toggle()methodOpen or close the suggestions (the caret does this for a pointer).
sg-chooseeventA suggestion was chosen. detail: { value }. The input also fires input and change, as typing would.
sg-skineventFires when a register's look has loaded.

Matching

  • Case, punctuation and extra spaces are ignored.
  • Accents are ignored on Latin letters: "Balcao" finds "Balcão", "Sao Jacinto" finds "São Jacinto". Devanagari, Kannada and other scripts keep their vowel signs, because there they are letters.
  • A match at the start of the name ranks first, then at the start of any word ("goa" finds "Old Goa"), then an alias ("Bombay", "मुंबई"), then a looser spelling match ("Tiruvanantapuram" finds Thiruvananthapuram), then three or more letters inside a word.
  • Equally good matches keep the order of your datalist.

Keyboard

KeyWhat it does
TypingFilters the suggestions and opens the list. Nothing is chosen for you.
Down ArrowOpens the list, or moves to the next suggestion (from the last, back to the first). Alt+Down opens without moving.
Up ArrowOpens the list at the last suggestion, or moves to the previous one.
EnterChooses the highlighted suggestion. With none highlighted, submits the form as usual.
EscapeCloses the list. With the list closed, clears the text.
TabCloses the list and moves on, keeping what was typed.
Left, Right, Home, EndBack to editing the text.

Registers

  • Quiet: a hairline input with a plain chevron, and a raised list with a bar beside the highlighted suggestion. The list appears without motion. Without JavaScript, the input keeps this look and the suggestions are the browser's own.
  • Warm: written on the paper like the field: no box, a pencil rule under the input (the field's own, from field/rule.js) that inks from left to right while you type in it, and stays inked under the words when you leave. A caret of two uneven pencil strokes. The list is edged in ink and ruled in pencil between suggestions; the highlighted suggestion's name is underlined in ink by hand, not filled. The list unfurls in about a quarter of a second.
  • Playful: a stamped box with an off-register ghost and a thick, round accent caret; suggestions are stamped chips, slightly tilted, and the highlighted one is filled. A choice lands on the input with a small press.

An input that is :user-invalid, or carries aria-invalid="true" for an error a server sends back, shows its edge (or its pencil rule, in warm) in the danger colour. Link the words with aria-describedby. The demo shows a filled-in value and a wrong one.

Accessibility

How this component meets WCAG 2.2 level A and AA, criterion by criterion, how each was checked, and what your page still owns.

  • Meets 17
  • Meets with author's part 4
  • Not applicable 1
CriterionStatusHow it was checked
1.1.1 Non-text contentMeetsThe chevron is aria-hidden (the arrow keys do what it does), and the warm pencil rule and caret are drawn behind the input (packages/components/combobox/combobox.check.mjs: "warm rests on a pencil rule with no box, and the caret is two pencil strokes"). The suggestions are text.
1.3.1 Info and relationshipsMeetsA native <label for> and <input>, which becomes role="combobox" with aria-autocomplete="list", aria-expanded and aria-controls a role="listbox" named by the label. combobox.check.mjs: "the input becomes a combobox with a list popup", "it controls a listbox named by the label", and the accessibility tree reads combobox "Travelling from" [expanded] and listbox "Travelling from".
1.3.5 Identify input purposeMeets with author's partThe component leaves the input's autocomplete alone (packages/components/combobox/combobox.js never sets it). The demo writes autocomplete="off" because its fields are not the reader's own address. A combobox that collects the reader's own city, state or country owns the matching autocomplete token.
1.4.1 Use of colorMeetsThe active suggestion is shown by a fill in quiet and an underline in warm (combobox.check.mjs: "warm: focus inks the rule; the active suggestion is underlined in ink, not filled") and is also the one named by aria-activedescendant; matched letters are marked with <mark>, not colour alone ("the matched letters are marked, accents and all").
1.4.3 Contrast (minimum)MeetsText is --sg-text and --sg-text-soft, tested at 4.5:1 or more on every surface in packages/tokens/tokens.test.js. tools/axe.mjs --url /packages/components/combobox/demo.html: 0 violation(s) across 6 run(s) (three registers, light and dark, desktop), 2026-10-07, and with the list open (axe-core, WCAG 2.2 AA tags, three registers, light): 0 violations, with color-contrast listed to review by hand.
1.4.4 Resize textMeetspackages/components/combobox/combobox.check.mjs: "<register>, 200% root font size, 1280x800: the list fits the viewport and the active option is on screen at every step" types "m" and walks ArrowDown through all five suggestions in quiet, warm and playful, in Chromium, WebKit and Firefox. It failed before the fix in quiet and warm (the fifth option at 751 to 831 px in an 800 px viewport); now the list ends at 792 px. combobox.js caps the list's height at the room on the roomier side of the input (--sg-combobox-room in combobox.css), so a long list scrolls inside itself. No text is clipped or scrolled sideways at 200 percent (manual test, 2026-10-07, throwaway Playwright script).
1.4.10 ReflowMeetsManual test at 320 CSS px, three registers, 2026-10-07: no sideways scroll with the list open; the list is 288 px wide inside the 16 px margins and every option is in view (throwaway Playwright script).
1.4.11 Non-text contrastMeetsThe input border and the list border are --sg-rule-strong and the focus ring is --sg-focus, tested 3:1 or more on every surface for every palette and theme in packages/tokens/tokens.test.js.
1.4.12 Text spacingMeetsManual test, 2026-10-07: the WCAG text-spacing values (line height 1.5, letter 0.12em, word 0.16em, paragraph spacing 2em) injected with the list open, three registers, no clipped or overlapping text and every option still readable (throwaway Playwright script). No check in the repository asserts it yet.
1.4.13 Content on hover or focusNot applicableThe list opens when the reader types, presses an arrow key or clicks the input or the caret (combobox.check.mjs: "typing opens the list", "a pointer can open the list and choose"), not when the pointer hovers or focus lands.
2.1.1 KeyboardMeetscombobox.check.mjs: Tab reaches the input, typing opens the list, Down and Up Arrow move (wrapping), Enter chooses and closes, Escape closes and keeps the text, Escape again clears it, and a place that is not in the list is kept.
2.1.2 No keyboard trapMeetscombobox.check.mjs: "Tab closes the list and moves on without choosing"; Escape closes it.
2.4.3 Focus orderMeetsFocus stays in the input while the suggestions are browsed (aria-activedescendant), and Tab goes on to the next control (combobox.check.mjs: "Down Arrow moves to the first option, focus stays in the input", "Tab closes the list and moves on").
2.4.7 Focus visibleMeetsThe input shows its focus ring in every register (tools/touch.check.mjs). The active option, named by aria-activedescendant, stays on screen at a 200 percent root font size: the same check as 1.4.4 asserts its box is inside the viewport and inside the list at each ArrowDown step, in all three registers (packages/components/combobox/combobox.check.mjs).
2.4.11 Focus not obscured (minimum)Meets with author's partManual test, 2026-10-07: nothing the component draws covers the input, and the list sits below it in the top layer (position: fixed in packages/components/combobox/combobox.css), so it covers other page content but never the focused input. A sticky bar the page adds can cover the input when it is scrolled to.
2.5.3 Label in nameMeetsThe input is named by its visible label (combobox.check.mjs: combobox "Travelling from"), and each option's name is its text.
2.5.8 Target size (minimum)MeetsThe input is at least 2.75rem (44 px) high and an option at least 2.5rem (40 px) (packages/components/combobox/combobox.css). Manual test, 2026-10-07: options measure 278 by 40 px in quiet and warm and 141 to 197 by 41 px in playful at 320 px, and no focusable control is under 24 by 24 px at 1280 px or at 390 px (throwaway Playwright script).
3.2.2 On inputMeetsTyping and arrowing change the list and the status line and nothing else. Choosing an option fills the input and closes the list, and the form submits only when the reader presses Enter again or the page's own button (combobox.check.mjs: "Enter chooses the option and closes the list", "a place not in the list is kept, and Enter submits the form").
3.3.1 Error identificationMeets with author's partrequired is the native attribute: combobox.check.mjs: "no JS: an empty required city stops the form". The demo shows an invalid field with aria-invalid="true" and aria-describedby pointing at a sentence that names the field and offers the valid choices ("There is no airport called Gova. Choose one from the list: Mopa (GOX) or Dabolim (GOI)"); that markup and wording are the page's, since the component does not validate.
3.3.2 Labels or instructionsMeets with author's partThe native <label for> is the name and aria-describedby can point at a hint (combobox.check.mjs: "it controls a listbox named by the label"). The label and hint words are the author's.
4.1.2 Name, role, valueMeetscombobox.check.mjs: role, aria-expanded, aria-activedescendant and aria-selected follow the state, and the tree reads combobox "Travelling from" [expanded] with options. axe: 0 violations, closed and open, 2026-10-07.
4.1.3 Status messagesMeetsA polite role="status" line says how many suggestions there are once typing settles, and only when the number changes (combobox.check.mjs: "the number of suggestions is said politely, once", "2 suggestions").

The page author owns:

  • The label, hint and error words, in the language of the page, and lang on an option list in another language (3.1.2).
  • The error markup: aria-invalid and an aria-describedby sentence that says what is wrong and what is valid (3.3.1).
  • The autocomplete token on a field that collects the reader's own details (1.3.5).
  • Sticky headers and banners that could cover the input when it takes focus (2.4.11).
  • The colours the page sets behind the input, if it overrides the tokens.

How it behaves

  • Follows the ARIA APG editable combobox with list autocomplete. Focus stays in the input; the highlighted suggestion is announced through aria-activedescendant, and the listbox is labelled by the input's label.
  • A polite status line says how many suggestions there are ("2 suggestions", "No suggestions") once typing settles, and only when the number changes.
  • The chevron is aria-hidden: the arrow keys do what it does.
  • The input is at least 44 pixels high, the suggestions at least 40.
  • With reduced motion, the list's entrance and the chevron's turn are off.
  • combobox.check.mjs checks the no-JavaScript form, every key above, the screen-reader tree, matching across scripts, and every register under reduced motion. Zero axe violations in every register, light and dark.

All 57 tables, and how the library tests