Chapter 43: ARIA States & Properties 🎛️

Building an Accessible Live Search / Autocomplete

Capstone widget architecture: Synchronizing `role="combobox"`, `aria-autocomplete`, `aria-activedescendant`, `aria-controls`, and live result announcements.

LEARNING OBJECTIVES ⌵

Implement the complete W3C WAI-ARIA 1.2 Combobox Design Pattern.
Master the Virtual Focus Mechanism using aria-activedescendant without losing native DOM focus on the <input>.
Coordinate multiple ARIA states in real time: aria-expanded, aria-selected, aria-autocomplete, and aria-controls.
Connect a polite live region announcer (role="status") to inform screen readers of dynamic search result counts.

🎬 INTERACTIVE VISUAL PIPELINE Core Architecture Simulation

🌐

1. Input

Directives & Tags

⚙️

2. Parse

Tokenizer & AST

🌳

3. Layout

Box Model & Flow

🎨

4. Render

GPU Paint & Composite

PHASE 1: INPUT & DIRECTIVES

Browser receives declarative markup stream, parsing tag tokens and initializing component state.

📖 The Mental Model & Story (Intuitive Foundation)

Imagine sitting in a library reading room with a research librarian assistant:

The Question Sheet (The Combobox Input): You hold a pen and paper. You write: "Quantum". Native physical focus never leaves your hand or your pen.
The Librarian's Quick Reference Tray (The Popup Listbox): The librarian instantly places a tray of 5 book cards on your desk.
The Laser Pointer (aria-activedescendant): Instead of ripping the pen out of your hand and dragging your body to the shelf (which would break your typing flow), the librarian shines a red laser pointer onto Card #1: "Quantum Computing Fundamentals".
The Whisper Assistant (The ARIA Live Announcer): The librarian gently whispers in your ear: "5 matching books found. Use up and down arrows to browse."

When building an autocomplete search widget, moving physical DOM focus (element.focus()) back and forth between the input box and dropdown <li> elements is a terrible anti-pattern: it destroys the user's cursor position, interferes with IME typing (Japanese, Chinese, Korean keyboards), and causes severe screen reader lag.

The aria-activedescendant Virtual Focus Pattern keeps native DOM focus locked onto the <input> at all times while projecting a virtual focus pointer onto the dropdown options.

Technical Deep Dive & Specifications

The ARIA 1.2 Combobox Anatomy

+-----------------------------------------------------------------------------------------------+
|                                  WAI-ARIA 1.2 COMBOBOX TOPOLOGY                               |
+-----------------------------------------------------------------------------------------------+
|                                                                                               |
|   <label id="search-label" for="search-input">Search Repositories</label>                     |
|                                                                                               |
|   <input                                                                                      |
|     id="search-input"                                                                         |
|     type="search"                                                                             |
|     role="combobox"                     <-- Declares widget type                              |
|     aria-labelledby="search-label"      <-- Accessible Name                                   |
|     aria-autocomplete="list"            <-- Autocomplete behavior                            |
|     aria-expanded="true"                <-- Dropdown visibility state                         |
|     aria-haspopup="listbox"             <-- Declares type of popup                            |
|     aria-controls="results-listbox"     <-- Target popup ID                                   |
|     aria-activedescendant="opt-2"       <-- Virtual focus pointer                             |
|   >                                                                                           |
|                                                                                               |
|   <ul id="results-listbox" role="listbox" aria-label="Suggestions">                           |
|     ├── <li id="opt-1" role="option" aria-selected="false">react</li>                         |
|     ├── <li id="opt-2" role="option" aria-selected="true">react-dom</li> <== [VIRTUAL FOCUS]  |
|     └── <li id="opt-3" role="option" aria-selected="false">react-router</li>                  |
|   </ul>                                                                                       |
|                                                                                               |
|   <div id="search-status" role="status" aria-atomic="true" class="sr-only">                   |
|     "3 repositories found. Use up and down arrows to navigate."                               |
|   </div>                                                                                      |
|                                                                                               |
+-----------------------------------------------------------------------------------------------+

The 4 Values of `aria-autocomplete`

Value	Behavior Description
`"list"`	Input text stays as typed; suggestions are presented in an external popup listbox. (Standard Google / GitHub search).
`"inline"`	The system automatically appends predicted text inline into the input box past the cursor.
`"both"`	Combines both: displays a popup list and autocompletes text inline into the input.
`"none"`	Freeform input with no autocomplete prediction.

How `aria-activedescendant` Works Under the Hood

Native hardware focus stays on the <input>. The user can continue typing or backspacing without interruption.

When the user presses ArrowDown, JavaScript sets:

input.setAttribute('aria-activedescendant', 'opt-2');

The browser looks up #opt-2 in the Accessibility Tree, checks its role (role="option"), name, and aria-selected state, and fires a focus event to the screen reader.
The screen reader announces: "react-dom, 2 of 3, selected".
JavaScript toggles a visual active CSS class (.is-active) on #opt-2 and updates aria-selected="true".

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

Line 66–75 (<input role="combobox" ...>): Sets up the WAI-ARIA 1.2 Combobox pattern with aria-autocomplete="list", aria-expanded="false", aria-haspopup="listbox", and aria-controls="framework-listbox".
Line 77–82 (<ul id="framework-listbox" role="listbox" ... hidden>): The controlled popup listbox containing individual options.
Line 85 (<div id="search-status" role="status" ...>): A pre-rendered polite live region that announces result counts dynamically upon typing.
Line 124 (status.textContent = '${items.length} suggestions available...'): Provides prompt auditory context without interrupting typing.
Line 169 (input.setAttribute('aria-activedescendant', opt.id)): Shifts virtual focus cleanly to the active option while physical keyboard focus remains seamlessly inside the <input>.

Expected Screen Reader Render Output

SYS: ACTIVE

HULL: 98%

CORE: STABLE

NET: ONLINE

HTML STARSHIP CODE TERMINAL playground.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Accessible Combobox Autocomplete Playground</title>
  <style>
    body { font-family: system-ui, sans-serif; padding: 24px; }
    
    .combobox-wrapper { position: relative; max-width: 400px; }
    label { display: block; font-weight: 600; margin-bottom: 6px; }
    
    .combo-input {
      width: 100%;
      padding: 10px 14px;
      font-size: 1rem;
      border: 2px solid #cbd5e1;
      border-radius: 6px;
      box-sizing: border-box;
    }
    .combo-input:focus {
      outline: none;
      border-color: #0284c7;
      box-shadow: 0 0 0 3px rgba(2, 132, 199, 0.2);
    }

.combo-popup {
      position: absolute;
      top: 100%;
      left: 0;
      right: 0;
      background: white;
      border: 1px solid #94a3b8;
      border-radius: 6px;
      margin-top: 4px;
      padding: 4px 0;
      list-style: none;
      box-shadow: 0 10px 15px -3px rgba(0,0,0,0.1);
      max-height: 200px;
      overflow-y: auto;
      z-index: 50;
    }
    .combo-popup[hidden] { display: none; }

.combo-option {
      padding: 8px 14px;
      cursor: pointer;
    }
    .combo-option.is-active,
    .combo-option[aria-selected="true"] {
      background: #0284c7;
      color: white;
    }

.sr-only {
      position: absolute !important;
      width: 1px !important;
      height: 1px !important;
      clip: rect(0,0,0,0) !important;
      border: 0 !important;
      overflow: hidden !important;
    }
  </style>
</head>
<body>

<div class="combobox-wrapper">
    <label id="framework-lbl" for="framework-search">Select JavaScript Framework:</label>
    
    <input 
      id="framework-search" 
      class="combo-input"
      type="text" 
      role="combobox"
      aria-labelledby="framework-lbl"
      aria-autocomplete="list"
      aria-expanded="false"
      aria-haspopup="listbox"
      aria-controls="framework-listbox"
      placeholder="Type 're', 'vu', 'an'..."
      autocomplete="off"
    >

<div id="search-status" role="status" aria-atomic="true" class="sr-only"></div>
  </div>

const input = document.getElementById('framework-search');
    const listbox = document.getElementById('framework-listbox');
    const status = document.getElementById('search-status');
    let activeIdx = -1;
    let matches = [];

input.addEventListener('input', () => {
      const query = input.value.trim().toLowerCase();
      activeIdx = -1;
      input.removeAttribute('aria-activedescendant');

if (!query) {
        closeListbox();
        status.textContent = '';
        return;
      }

matches = frameworks.filter(f => f.toLowerCase().includes(query));
      renderOptions(matches);
    });

function renderOptions(items) {
      listbox.innerHTML = '';
      if (items.length === 0) {
        closeListbox();
        status.textContent = 'No matching frameworks found.';
        return;
      }

items.forEach((item, idx) => {
        const li = document.createElement('li');
        li.id = `opt-${idx}`;
        li.className = 'combo-option';
        li.role = 'option';
        li.setAttribute('aria-selected', 'false');
        li.textContent = item;
        li.addEventListener('click', () => selectOption(item));
        listbox.appendChild(li);
      });

openListbox();
      status.textContent = `${items.length} suggestions available. Use up and down arrows to navigate.`;
    }

function openListbox() {
      listbox.removeAttribute('hidden');
      input.setAttribute('aria-expanded', 'true');
    }

function closeListbox() {
      listbox.setAttribute('hidden', '');
      input.setAttribute('aria-expanded', 'false');
      input.removeAttribute('aria-activedescendant');
      activeIdx = -1;
    }

function selectOption(value) {
      input.value = value;
      closeListbox();
      input.focus();
      status.textContent = `Selected ${value}.`;
    }

input.addEventListener('keydown', (e) => {
      const options = listbox.querySelectorAll('[role="option"]');
      if (!options.length || listbox.hasAttribute('hidden')) return;

if (e.key === 'ArrowDown') {
        e.preventDefault();
        activeIdx = (activeIdx + 1) % options.length;
        updateActiveDescendant(options);
      } else if (e.key === 'ArrowUp') {
        e.preventDefault();
        activeIdx = (activeIdx - 1 + options.length) % options.length;
        updateActiveDescendant(options);
      } else if (e.key === 'Enter') {
        if (activeIdx >= 0) {
          e.preventDefault();
          selectOption(options[activeIdx].textContent);
        }
      } else if (e.key === 'Escape') {
        e.preventDefault();
        closeListbox();
      }
    });

// Close on click outside
    document.addEventListener('click', (e) => {
      if (!e.target.closest('.combobox-wrapper')) {
        closeListbox();
      }
    });
  </script>

</body>
</html>

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

[User types "re"]
Live Announcer speaks: "4 suggestions available. Use up and down arrows to navigate."

[User presses ArrowDown]
Screen Reader speaks: "React, 1 of 4, selected"

[User presses ArrowDown again]
Screen Reader speaks: "React Native, 2 of 4, selected"

[User presses Enter]
Input populated with "React Native", dropdown closes, live region announces "Selected React Native."

🏋️ Hands-On Exercise

🎯 The Challenge: Add Keyboard Autopopulate & Escape Revert

Instructions:

Extend the combobox playground above.
Track the user's raw typed query in a variable userTypedText.
When the user navigates options using ArrowDown / ArrowUp, temporarily reflect the active option's text inside input.value without submitting.
When the user presses Escape:
- Revert input.value back to userTypedText.
- Close the listbox (aria-expanded="false").
- Clear aria-activedescendant.
- Announce: "Search restored to [userTypedText]" in the live region.

🏁 Starter Code Sandbox

SYS: ACTIVE

HULL: 98%

CORE: STABLE

NET: ONLINE

STARTER CODE SANDBOX exercise.html

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Combobox Revert Solution</title>
  <style>
    body { font-family: system-ui, sans-serif; padding: 24px; }
    .combobox-box { max-width: 400px; position: relative; }
    label { font-weight: 600; display: block; margin-bottom: 6px; }
    input { width: 100%; padding: 10px 14px; font-size: 1rem; border: 2px solid #94a3b8; border-radius: 6px; box-sizing: border-box; }
    ul { list-style: none; padding: 0; margin: 4px 0 0 0; border: 1px solid #94a3b8; border-radius: 6px; position: absolute; width: 100%; background: white; max-height: 180px; overflow-y: auto; z-index: 10; }
    li { padding: 8px 12px; cursor: pointer; }
    li[aria-selected="true"] { background: #0284c7; color: white; }
    .sr-only { position: absolute !important; width: 1px !important; height: 1px !important; clip: rect(0,0,0,0) !important; border: 0 !important; overflow: hidden !important; }
  </style>
</head>
<body>

  <div class="combobox-box">
    <label id="city-lbl" for="city-input">Search Global Cities:</label>
    <input 
      id="city-input" 
      type="text" 
      role="combobox"
      aria-labelledby="city-lbl"
      aria-autocomplete="list"
      aria-expanded="false"
      aria-controls="city-listbox"
      autocomplete="off"
    >
    <ul id="city-listbox" role="listbox" aria-label="City suggestions" hidden></ul>
    <div id="city-status" role="status" aria-atomic="true" class="sr-only"></div>
  </div>

  <script>
    const cities = ["Tokyo", "Toronto", "Toulouse", "Taipei", "Tampa", "Tbilisi"];
    const input = document.getElementById('city-input');
    const listbox = document.getElementById('city-listbox');
    const status = document.getElementById('city-status');
    
    let userTypedText = '';
    let activeIdx = -1;

    input.addEventListener('input', () => {
      userTypedText = input.value;
      activeIdx = -1;
      const query = userTypedText.trim().toLowerCase();
      
      if (!query) {
        listbox.setAttribute('hidden', '');
        input.setAttribute('aria-expanded', 'false');
        status.textContent = '';
        return;
      }

      const matches = cities.filter(c => c.toLowerCase().includes(query));
      listbox.innerHTML = '';
      
      if (matches.length === 0) {
        listbox.setAttribute('hidden', '');
        input.setAttribute('aria-expanded', 'false');
        status.textContent = 'No matching cities.';
        return;
      }

      matches.forEach((city, i) => {
        const li = document.createElement('li');
        li.id = `city-opt-${i}`;
        li.role = 'option';
        li.setAttribute('aria-selected', 'false');
        li.textContent = city;
        li.onclick = () => {
          input.value = city;
          userTypedText = city;
          closeBox();
        };
        listbox.appendChild(li);
      });

      listbox.removeAttribute('hidden');
      input.setAttribute('aria-expanded', 'true');
      status.textContent = `${matches.length} cities found. Use arrows to browse.`;
    });

    input.addEventListener('keydown', (e) => {
      const options = listbox.querySelectorAll('[role="option"]');
      if (!options.length || listbox.hasAttribute('hidden')) return;

      if (e.key === 'ArrowDown') {
        e.preventDefault();
        activeIdx = (activeIdx + 1) % options.length;
        syncActive(options);
      } else if (e.key === 'ArrowUp') {
        e.preventDefault();
        activeIdx = (activeIdx - 1 + options.length) % options.length;
        syncActive(options);
      } else if (e.key === 'Enter') {
        if (activeIdx >= 0) {
          e.preventDefault();
          input.value = options[activeIdx].textContent;
          userTypedText = input.value;
          closeBox();
        }
      } else if (e.key === 'Escape') {
        e.preventDefault();
        input.value = userTypedText;
        closeBox();
        status.textContent = `Search reverted to "${userTypedText}".`;
      }
    });

    function syncActive(options) {
      options.forEach((opt, idx) => {
        const isSelected = idx === activeIdx;
        opt.setAttribute('aria-selected', String(isSelected));
        if (isSelected) {
          input.setAttribute('aria-activedescendant', opt.id);
          input.value = opt.textContent; // Temporarily reflect option value
          opt.scrollIntoView({ block: 'nearest' });
        }
      });
    }

    function closeBox() {
      listbox.setAttribute('hidden', '');
      input.setAttribute('aria-expanded', 'false');
      input.removeAttribute('aria-activedescendant');
      activeIdx = -1;
    }
  </script>
</body>
</html>

Why this works:

Stores userTypedText on typing, updates input.value temporarily during arrow traversal, and cleanly restores original typed text on Escape.
Keeps keyboard focus securely in the input while providing seamless auditory feedback on every state transition.

⚠️ Common Pitfalls

Moving DOM Focus to the Dropdown Options: Never call optionElement.focus(). Focus must remain on the <input> so the user can continue typing without re-clicking.
Missing aria-selected="true": Setting aria-activedescendant is not enough; you must also toggle aria-selected="true" on the targeted option.
Spamming Live Regions on Fast Keystrokes: Typing rapidly can queue dozens of live region announcements. Always debounce search result announcements by 300ms.

💡 Pro Tips

ARIA 1.2 vs ARIA 1.0 Combobox Specs: In ARIA 1.0, role="combobox" was placed on a wrapper <div> with an <input> child. In ARIA 1.2, role="combobox" is placed directly on the <input> element itself. Always use the ARIA 1.2 pattern for modern web applications.
Scroll Into View Alignment: When traversing long suggestion lists, use opt.scrollIntoView({ block: 'nearest' }) so that the focused option is always visible in the listbox without causing the whole webpage to scroll.

📌 Key Takeaways

The WAI-ARIA 1.2 Combobox places role="combobox" directly on the <input>.
aria-activedescendant creates a virtual focus pointer, allowing options to be selected without moving physical DOM focus away from the input.
Synchronize aria-expanded, aria-controls, and aria-selected on every keystroke.
Use a polite live region (role="status") to announce result count metrics to screen readers.
Support comprehensive keyboard commands: ArrowDown/ArrowUp (traverse), Enter (select), Escape (dismiss/revert).
--

⭐ LEARN: HTML 🌟 ⚔️ QUIZ BATTLE ARENA // ACTIVE

? Question 1 / 3

Why does the WAI-ARIA Combobox pattern use `aria-activedescendant` instead of shifting native DOM focus (`element.focus()`) to each option?

Topic: HTML Fundamentals

? Question 2 / 3

Where should `role="combobox"` be placed according to the modern WAI-ARIA 1.2 specification?

Topic: HTML Fundamentals

? Question 3 / 3

What value of `aria-autocomplete` indicates that suggestions are rendered in a separate popup list without automatic inline text completion?

Topic: HTML Fundamentals

👨‍🚀 CADET FLIGHT DOSSIER

CADET EXPLORER

📖 The Mental Model & Story (Intuitive Foundation)

Technical Deep Dive & Specifications

The ARIA 1.2 Combobox Anatomy

The 4 Values of aria-autocomplete

How aria-activedescendant Works Under the Hood

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

Expected Screen Reader Render Output

🏋️ Hands-On Exercise

🎯 The Challenge: Add Keyboard Autopopulate & Escape Revert

🏁 Starter Code Sandbox

⚠️ Common Pitfalls

💡 Pro Tips

📌 Key Takeaways

Why does the WAI-ARIA Combobox pattern use aria-activedescendant instead of shifting native DOM focus (element.focus()) to each option?

Where should role="combobox" be placed according to the modern WAI-ARIA 1.2 specification?

What value of aria-autocomplete indicates that suggestions are rendered in a separate popup list without automatic inline text completion?

The 4 Values of `aria-autocomplete`

How `aria-activedescendant` Works Under the Hood

Why does the WAI-ARIA Combobox pattern use `aria-activedescendant` instead of shifting native DOM focus (`element.focus()`) to each option?

Where should `role="combobox"` be placed according to the modern WAI-ARIA 1.2 specification?

What value of `aria-autocomplete` indicates that suggestions are rendered in a separate popup list without automatic inline text completion?