ARIA Practical Guide: Implementing Accessible Web Interfaces

<!-- ❌ Bad: Unnecessary ARIA -->
<button role="button" aria-label="Click">Click</button>
<!-- <button> is already a button; role is redundant -->

<!-- ❌ Bad: ARIA used when semantic HTML exists -->
<div role="heading" aria-level="1">Title</div>
<!-- Use <h1>Title</h1> instead -->

<!-- ❌ Bad: aria-label when visible text already exists -->
<button aria-label="Save">
  <i class="icon-save"></i> Save
</button>
<!-- If visible text exists, aria-label is unnecessary -->

<!-- ✅ Good: No ARIA needed (semantic HTML is enough) -->
<button>Save</button>
<h1>Title</h1>
<form>
  <label for="email">Email</label>
  <input id="email" type="email">
</form>

<!-- ✅ Case 1: Custom widget -->
<div class="custom-tabs">
  <div role="tablist">
    <button role="tab" aria-selected="true" aria-controls="panel-1" tabindex="0">
      Tab 1
    </button>
    <button role="tab" aria-selected="false" aria-controls="panel-2" tabindex="-1">
      Tab 2
    </button>
  </div>
  <div id="panel-1" role="tabpanel">Content 1</div>
  <div id="panel-2" role="tabpanel" hidden>Content 2</div>
</div>

<!-- ✅ Case 2: Additional info -->
<button aria-label="Open chart">📊</button>
<!-- Icon-only button requires aria-label -->

<!-- ✅ Case 3: Announce state change -->
<span aria-live="polite" aria-atomic="true" id="notifications"></span>
<script>
  // Add message after user action
  document.getElementById('notifications').textContent = 'Saved.';
</script>

<!-- 1. aria-label: simple label -->
<button aria-label="Close">×</button>

<!-- 2. aria-labelledby: reference another element -->
<h2 id="dialog-title">User Settings</h2>
<div role="dialog" aria-labelledby="dialog-title">
  <!-- Dialog content -->
</div>

<!-- 3. Combine labels from multiple elements -->
<span id="search-label">Product search</span>
<span id="search-hint">(name, category)</span>
<input
  aria-labelledby="search-label search-hint"
  placeholder="Search"
>

<!-- 4. Visually hidden label -->
<style>
  .sr-only {
    position: absolute;
    width: 1px;
    height: 1px;
    padding: 0;
    margin: -1px;
    overflow: hidden;
    clip: rect(0, 0, 0, 0);
    border: 0;
  }
</style>

<button>
  <span class="sr-only">Back</span>
  ←
</button>

<!-- Additional help text -->
<label for="password">Password</label>
<input
  id="password"
  type="password"
  aria-describedby="pwd-requirements pwd-strength"
>
<div id="pwd-requirements" class="hint">
  Minimum 8 chars, include uppercase, numbers, and symbols (@, #, $)
</div>
<div id="pwd-strength" aria-live="polite">
  Strength: Weak
</div>

<!-- Complex image description -->
<img
  src="chart.png"
  alt="Monthly sales"
  aria-describedby="chart-desc"
>
<p id="chart-desc">
  Sales from January to December 2024.
  Peak in July at 15,000 units, lowest in February at 5,000.
</p>

<!-- Error message -->
<label for="email">Email</label>
<input id="email" type="email" aria-describedby="email-error">
<span id="email-error" role="alert">
  Please enter a valid email address.
</span>

<!-- 1. Checkbox/radio state -->
<label>
  <input type="checkbox">
  I agree to the terms
</label>

<!-- Native checkbox/radio already exposes state.
     Use aria-checked only for custom widgets. -->

<!-- 2. Toggle button state -->
<button
  aria-pressed="false"
  aria-label="Mute"
  id="mute-btn"
>
  🔊
</button>

<script>
  const muteBtn = document.getElementById('mute-btn');
  muteBtn.addEventListener('click', function() {
    const isPressed = this.getAttribute('aria-pressed') === 'true';
    this.setAttribute('aria-pressed', !isPressed);
    // Toggle mute logic
  });
</script>

<!-- 3. Current page in navigation -->
<nav>
  <a href="/products">Products</a>
  <a href="/blog" aria-current="page">Blog</a>
  <a href="/about">About</a>
</nav>

<!-- 4. Expand/collapse state -->
<button aria-expanded="false" aria-controls="submenu">
  Categories
</button>
<ul id="submenu" hidden>
  <li><a href="#">Submenu 1</a></li>
  <li><a href="#">Submenu 2</a></li>
</ul>

<script>
  document.querySelector('button').addEventListener('click', function() {
    const isExpanded = this.getAttribute('aria-expanded') === 'true';
    this.setAttribute('aria-expanded', !isExpanded);
    document.getElementById('submenu').hidden = isExpanded;
  });
</script>

<!-- 1. aria-live="polite" (default) -->
<!-- Announces after the user finishes the current task -->
<div id="notifications" aria-live="polite">
  <!-- Messages appear here -->
</div>

<!-- 2. aria-live="assertive" -->
<!-- Announces immediately (use for urgent alerts only) -->
<div id="error-alert" aria-live="assertive">
  <!-- Immediate error message -->
</div>

<!-- 3. aria-atomic="true" -->
<!-- Announces the whole region, not just the changed part -->
<div aria-live="polite" aria-atomic="true" id="search-results">
  <p>Results: 23</p>
  <ul>
    <li>Item 1</li>
    <li>Item 2</li>
  </ul>
</div>

<!-- 4. aria-relevant="additions text" -->
<!-- Control which changes are announced -->
<div aria-live="polite" aria-relevant="additions text">
  <!-- Only additions and text changes announced -->
</div>

<div class="search-container">
  <input
    id="search-input"
    type="text"
    placeholder="Search..."
    aria-describedby="search-help"
  >
  <span id="search-help" class="sr-only">
    Results update as you type.
  </span>
</div>

<!-- Live region for search results -->
<div
  id="search-results"
  role="status"
>
  <!-- Results appear here -->
</div>

<script>
  const input = document.getElementById('search-input');
  const resultsDiv = document.getElementById('search-results');

  input.addEventListener('input', function(e) {
    const query = e.target.value.trim();

    if (!query) {
      resultsDiv.innerHTML = '';
      return;
    }

    // API request (example)
    fetch(`/api/search?q=${query}`)
      .then(res => res.json())
      .then(data => {
        resultsDiv.innerHTML = `
          <p>
            Found ${data.count} results.
          </p>
          <ul>
            ${data.items.map(item => `<li>${item.name}</li>`).join('')}
          </ul>
        `;
      });
  });
</script>

<div class="tabs">
  <div role="tablist">
    <button
      role="tab"
      aria-selected="true"
      aria-controls="panel-1"
      tabindex="0"
      id="tab-1"
    >
      Basic Info
    </button>
    <button
      role="tab"
      aria-selected="false"
      aria-controls="panel-2"
      tabindex="-1"
      id="tab-2"
    >
      Details
    </button>
  </div>

  <div id="panel-1" role="tabpanel" aria-labelledby="tab-1">
    Basic info content
  </div>
  <div id="panel-2" role="tabpanel" aria-labelledby="tab-2" hidden>
    Detailed content
  </div>
</div>

<style>
  [role="tab"][aria-selected="false"] {
    opacity: 0.6;
  }
</style>

<script>
  const tabs = document.querySelectorAll('[role="tab"]');
  const panels = document.querySelectorAll('[role="tabpanel"]');

  tabs.forEach(tab => {
    tab.addEventListener('click', function() {
      // Deactivate all tabs
      tabs.forEach(t => {
        t.setAttribute('aria-selected', 'false');
        t.setAttribute('tabindex', '-1');
      });
      panels.forEach(p => p.hidden = true);

      // Activate clicked tab
      this.setAttribute('aria-selected', 'true');
      this.setAttribute('tabindex', '0');
      const panelId = this.getAttribute('aria-controls');
      document.getElementById(panelId).hidden = false;
    });

    // Keyboard navigation
    tab.addEventListener('keydown', function(e) {
      let nextTab;
      if (e.key === 'ArrowRight' || e.key === 'ArrowDown') {
        nextTab = this.nextElementSibling || tabs[0];
      } else if (e.key === 'ArrowLeft' || e.key === 'ArrowUp') {
        nextTab = this.previousElementSibling || tabs[tabs.length - 1];
      } else if (e.key === 'Home') {
        nextTab = tabs[0];
      } else if (e.key === 'End') {
        nextTab = tabs[tabs.length - 1];
      }

      if (nextTab) {
        e.preventDefault();
        nextTab.click();
        nextTab.setAttribute('tabindex', '0');
        this.setAttribute('tabindex', '-1');
        nextTab.focus();
      }
    });
  });
</script>

<div class="accordion">
  <div class="accordion-item">
    <button
      aria-expanded="false"
      aria-controls="section-1"
      id="accordion-1"
      class="accordion-btn"
    >
      FAQ 1
    </button>
    <div
      id="section-1"
      role="region"
      aria-labelledby="accordion-1"
      hidden
      class="accordion-content"
    >
      <p>Answer 1</p>
    </div>
  </div>

  <div class="accordion-item">
    <button
      aria-expanded="false"
      aria-controls="section-2"
      id="accordion-2"
      class="accordion-btn"
    >
      FAQ 2
    </button>
    <div
      id="section-2"
      role="region"
      aria-labelledby="accordion-2"
      hidden
      class="accordion-content"
    >
      <p>Answer 2</p>
    </div>
  </div>
</div>

<style>
  .accordion-content {
    max-height: 0;
    overflow: hidden;
    transition: max-height 0.3s ease;
  }

  .accordion-content:not([hidden]) {
    max-height: 500px;
  }

  button[aria-expanded="true"]::after {
    content: '▼';
  }

  button[aria-expanded="false"]::after {
    content: '▶';
  }
</style>

<script>
  document.querySelectorAll('.accordion-btn').forEach(btn => {
    btn.addEventListener('click', function() {
      const isExpanded = this.getAttribute('aria-expanded') === 'true';
      this.setAttribute('aria-expanded', !isExpanded);
      document.getElementById(this.getAttribute('aria-controls')).hidden = isExpanded;
    });
  });
</script>

<div class="dropdown">
  <button
    id="menu-btn"
    aria-expanded="false"
    aria-controls="menu-list"
  >
    Menu
  </button>

  <ul id="menu-list" hidden aria-labelledby="menu-btn">
    <li><a href="#">Option 1</a></li>
    <li><a href="#">Option 2</a></li>
    <li><a href="#">Option 3</a></li>
  </ul>
</div>

<script>
  const btn = document.getElementById('menu-btn');
  const menu = document.getElementById('menu-list');
  const items = menu.querySelectorAll('a');

  btn.addEventListener('click', () => {
    const isExpanded = btn.getAttribute('aria-expanded') === 'true';
    btn.setAttribute('aria-expanded', !isExpanded);
    menu.hidden = isExpanded;

    if (!isExpanded) {
      items[0].focus();
    }
  });

  // Close on Escape
  menu.addEventListener('keydown', (e) => {
    if (e.key === 'Escape') {
      btn.click();
      btn.focus();
    }
  });

  // Close on outside click
  document.addEventListener('click', (e) => {
    if (!e.target.closest('.dropdown')) {
      menu.hidden = true;
      btn.setAttribute('aria-expanded', 'false');
    }
  });
</script>

<button id="open-modal">Open modal</button>

<div
  id="modal"
  role="dialog"
  aria-labelledby="modal-title"
  aria-modal="true"
  hidden
>
  <div class="modal-content">
    <h2 id="modal-title">Important Info</h2>

    <p>This is modal content.</p>

    <button id="close-modal">Close</button>
  </div>
</div>

<style>
  #modal:not([hidden]) {
    display: flex;
    position: fixed;
    top: 0;
    left: 0;
    width: 100%;
    height: 100%;
    background: rgba(0, 0, 0, 0.5);
  }

  .modal-content {
    margin: auto;
    background: white;
    padding: 2rem;
    border-radius: 8px;
  }
</style>

<script>
  const modal = document.getElementById('modal');
  const openBtn = document.getElementById('open-modal');
  const closeBtn = document.getElementById('close-modal');
  let previousFocus = null;

  openBtn.addEventListener('click', () => {
    previousFocus = document.activeElement;
    modal.hidden = false;
    // Inert everything except the modal
    const siblings = Array.from(document.body.children).filter(el => el !== modal);
    siblings.forEach(el => (el.inert = true));

    // Move focus into the modal
    const focusableElements = modal.querySelectorAll(
      'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
    );
    focusableElements[0]?.focus();

    // Focus trap inside modal
    focusableElements[focusableElements.length - 1].addEventListener('keydown', (e) => {
      if (e.key === 'Tab' && !e.shiftKey) {
        e.preventDefault();
        focusableElements[0].focus();
      }
    });

    focusableElements[0].addEventListener('keydown', (e) => {
      if (e.key === 'Tab' && e.shiftKey) {
        e.preventDefault();
        focusableElements[focusableElements.length - 1].focus();
      }
    });
  });

  closeBtn.addEventListener('click', () => {
    modal.hidden = true;
    const siblings = Array.from(document.body.children).filter(el => el !== modal);
    siblings.forEach(el => (el.inert = false));
    previousFocus?.focus();
  });

  // Close on Escape
  document.addEventListener('keydown', (e) => {
    if (e.key === 'Escape' && !modal.hidden) {
      closeBtn.click();
    }
  });
</script>

<!-- ❌ Mistake 1: Misusing roles -->
<div role="button" onclick="alert('Click')">Click me</div>
<!-- Issue: no keyboard focus, no keyboard activation -->

<!-- ✅ Correct -->
<button onclick="alert('Click')">Click me</button>

<!-- ❌ Mistake 2: aria-label without a visible label -->
<input aria-label="Search" placeholder="Search">
<!-- Issue: visible users see no label, assistive tech gets a label -->

<!-- ✅ Correct -->
<label for="search">Search</label>
<input id="search" placeholder="Search">

<!-- ❌ Mistake 3: Overusing live regions -->
<div aria-live="assertive" id="log">
  Log messages...
</div>
<!-- Issue: announces everything, can be noisy -->

<!-- ✅ Correct -->
<div aria-live="polite" aria-atomic="false" id="notification">
  <!-- Only latest message -->
</div>

<!-- ❌ Mistake 4: Inconsistent tabindex in tabs -->
<div role="tablist">
  <div role="tab" tabindex="0">First</div>
  <div role="tab">Second</div> <!-- missing tabindex -->
  <div role="tab" tabindex="0">Third</div>
</div>
<!-- Issue: inconsistent focus order -->

<!-- ✅ Correct: only first tab is 0, others are -1 -->
<div role="tablist">
  <div role="tab" tabindex="0">First</div>
  <div role="tab" tabindex="-1">Second</div>
  <div role="tab" tabindex="-1">Third</div>
</div>

<!-- 1. Avoid duplicating roles on native elements -->
<button>Good</button>
<div role="button">Use only when needed</div>

<!-- 2. Prefer changing elements over changing roles -->
<!-- ❌ Not good -->
<div id="button" role="button">Click</div>
<script>
  document.getElementById('button').setAttribute('role', 'link');
</script>

<!-- ✅ Good -->
<button>Click</button>

<!-- 3. Explicitly define composite roles -->
<div role="tablist">
  <div role="tab">Tab 1</div>
  <div role="tabpanel">Content 1</div>
</div>

/* Style based on ARIA state */
button[aria-pressed="true"] {
  background-color: #4A90E2;
  color: white;
}

button[aria-pressed="false"] {
  background-color: #f0f0f0;
  color: #333;
}

/* Focus indicators */
[role="button"]:focus {
  outline: 3px solid #4A90E2;
  outline-offset: 2px;
}

/* Optional: visualize live regions */
[aria-live="polite"] {
  border-left: 3px solid #27AE60;
  padding-left: 0.5rem;
}

/* Hidden panels */
[role="tabpanel"][hidden] {
  display: none;
}

// ❌ Bad: append each update individually
const notifications = document.getElementById('notifications');
for (let i = 0; i < 1000; i++) {
  notifications.innerHTML += `<p>Notification ${i}</p>`;
}

// ✅ Good: batch updates
const notifications = document.getElementById('notifications');
const fragment = document.createDocumentFragment();
for (let i = 0; i < 1000; i++) {
  const p = document.createElement('p');
  p.textContent = `Notification ${i}`;
  fragment.appendChild(p);
}
notifications.appendChild(fragment);

// ✅ Good: keep only the latest message
const notification = document.getElementById('notification');
function showNotification(message) {
  notification.innerHTML = message;
  setTimeout(() => {
    notification.innerHTML = '';
  }, 5000);
}

// React example
function Tabs() {
  const [selected, setSelected] = useState(0);

  return (
    <div role="tablist">
      {tabs.map((tab, i) => (
        <button
          key={i}
          role="tab"
          aria-selected={i === selected}
          aria-controls={`panel-${i}`}
          onClick={() => setSelected(i)}
        >
          {tab.label}
        </button>
      ))}
      {tabs.map((tab, i) => (
        <div
          key={i}
          id={`panel-${i}`}
          role="tabpanel"
          aria-labelledby={`tab-${i}`}
          hidden={i !== selected}
        >
          {tab.content}
        </div>
      ))}
    </div>
  );
}