ARIA: Accessible Rich Internet Applications Guide

<!-- ❌ Bad: Using ARIA on a div to make a button -->
<div role="button" tabindex="0" onclick="submitForm()">
  Submit
</div>

<!-- ✅ Good: Just use a native button -->
<button onclick="submitForm()">
  Submit
</button>

<!-- Using native HTML5 landmarks (preferred) -->
<header>
  <nav aria-label="Main">
    <ul><!-- nav links --></ul>
  </nav>
</header>

<main>
  <h1>Page Title</h1>
  <section aria-labelledby="section-heading">
    <h2 id="section-heading">Section Title</h2>
    <p>Content here...</p>
  </section>
</main>

<footer>
  <p>&copy; 2026 DodaTech</p>
</footer>

<!-- Custom tab widget using ARIA -->
<div role="tablist" aria-label="Product information">
  <button role="tab" aria-selected="true" aria-controls="panel-1" id="tab-1">
    Description
  </button>
  <button role="tab" aria-selected="false" aria-controls="panel-2" id="tab-2">
    Specifications
  </button>
  <button role="tab" aria-selected="false" aria-controls="panel-3" id="tab-3">
    Reviews
  </button>
</div>

<div role="tabpanel" id="panel-1" aria-labelledby="tab-1">
  <p>Product description content...</p>
</div>
<div role="tabpanel" id="panel-2" aria-labelledby="tab-2" hidden>
  <p>Technical specifications...</p>
</div>
<div role="tabpanel" id="panel-3" aria-labelledby="tab-3" hidden>
  <p>Customer reviews...</p>
</div>

<!-- aria-label — overrides visible text -->
<button aria-label="Close dialog" onclick="closeDialog()">×</button>

<!-- aria-labelledby — references another element's text -->
<h2 id="dialog-title">Confirm Deletion</h2>
<p id="dialog-desc">Are you sure you want to delete your account?</p>
<div role="dialog" aria-labelledby="dialog-title" aria-describedby="dialog-desc">
  <button onclick="confirmDelete()">Delete</button>
  <button onclick="cancelDelete()">Cancel</button>
</div>

<!-- aria-describedby — provides additional context -->
<label for="password">Password</label>
<input type="password" id="password"
       aria-describedby="password-hint">
<p id="password-hint">Must be at least 8 characters with a number</p>

<!-- aria-live="polite" — announces when idle -->
<div aria-live="polite" aria-atomic="true">
  Cart: 3 items
</div>

<!-- aria-live="assertive" — interrupts immediately (use sparingly) -->
<div role="alert">
  Error: Failed to save changes
</div>

<!-- aria-relevant — what changes trigger announcements -->
<!-- "additions" (default), "removals", "text", "all" -->
<ul aria-live="polite" aria-relevant="additions" id="notification-list">
  <!-- new notifications appear here -->
</ul>

<!-- aria-expanded — for accordions, menus, disclosures -->
<button aria-expanded="false" aria-controls="section-1">
  More Information
</button>
<div id="section-1" hidden>
  <p>Hidden content revealed when expanded...</p>
</div>

<!-- aria-hidden — hides decorative elements from AT -->
<span aria-hidden="true">→</span> Next Page

<!-- aria-current — indicates current item in a set -->
<nav aria-label="Breadcrumb">
  <ol>
    <li><a href="/">Home</a></li>
    <li><a href="/products">Products</a></li>
    <li><a href="/products/laptop" aria-current="page">Laptop</a></li>
  </ol>
</nav>

<!-- aria-disabled — disabled state that works with all elements -->
<button aria-disabled="true">Submit</button>

<div role="tablist" aria-label="Documentation">
  <button role="tab" aria-selected="true" aria-controls="panel-1" id="tab-1">
    Getting Started
  </button>
  <button role="tab" aria-selected="false" aria-controls="panel-2" id="tab-2">
    API Reference
  </button>
</div>
<div role="tabpanel" id="panel-1" aria-labelledby="tab-1">
  <h2>Getting Started</h2>
  <p>Content for the first tab...</p>
</div>
<div role="tabpanel" id="panel-2" aria-labelledby="tab-2" hidden>
  <h2>API Reference</h2>
  <p>Content for the second tab...</p>
</div>

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

  tabs.forEach(tab => {
    tab.addEventListener('click', () => activateTab(tab));
    tab.addEventListener('keydown', (e) => {
      const tabList = e.target.closest('[role="tablist"]');
      const tabs = [...tabList.querySelectorAll('[role="tab"]')];
      const idx = tabs.indexOf(e.target);

      if (e.key === 'ArrowRight' && idx < tabs.length - 1) {
        activateTab(tabs[idx + 1]);
        tabs[idx + 1].focus();
      } else if (e.key === 'ArrowLeft' && idx > 0) {
        activateTab(tabs[idx - 1]);
        tabs[idx - 1].focus();
      }
    });
  });

  function activateTab(tab) {
    // Deselect all
    tabs.forEach(t => {
      t.setAttribute('aria-selected', 'false');
    });
    panels.forEach(p => p.hidden = true);

    // Select target
    tab.setAttribute('aria-selected', 'true');
    const panel = document.getElementById(tab.getAttribute('aria-controls'));
    if (panel) panel.hidden = false;
  }
}

initTabs();
</script>

<div>
  <h3>
    <button aria-expanded="false" aria-controls="faq-1" id="faq-btn-1">
      What is WCAG?
    </button>
  </h3>
  <div id="faq-1" role="region" aria-labelledby="faq-btn-1" hidden>
    <p>WCAG stands for Web Content Accessibility Guidelines...</p>
  </div>

  <h3>
    <button aria-expanded="false" aria-controls="faq-2" id="faq-btn-2">
      What is ARIA?
    </button>
  </h3>
  <div id="faq-2" role="region" aria-labelledby="faq-btn-2" hidden>
    <p>ARIA stands for Accessible Rich Internet Applications...</p>
  </div>
</div>

<script>
function initAccordion() {
  document.querySelectorAll('[aria-expanded]').forEach(btn => {
    btn.addEventListener('click', () => {
      const expanded = btn.getAttribute('aria-expanded') === 'true';
      btn.setAttribute('aria-expanded', !expanded);
      const panel = document.getElementById(btn.getAttribute('aria-controls'));
      if (panel) panel.hidden = expanded;
    });
  });
}
initAccordion();
</script>

<button onclick="openModal()">Open Settings</button>

<div role="dialog"
     aria-modal="true"
     aria-labelledby="modal-title"
     id="settings-modal"
     hidden>
  <div role="document">
    <h2 id="modal-title">Settings</h2>
    <p>Configure your preferences below.</p>

    <label for="theme">Theme</label>
    <select id="theme">
      <option>Light</option>
      <option>Dark</option>
    </select>

    <button onclick="saveSettings()">Save</button>
    <button onclick="closeModal()" aria-label="Close settings">×</button>
  </div>
</div>

<div id="modal-backdrop" hidden></div>

<script>
function openModal() {
  const modal = document.getElementById('settings-modal');
  const backdrop = document.getElementById('modal-backdrop');
  modal.hidden = false;
  backdrop.hidden = false;
  // Focus first focusable element
  modal.querySelector('button, input, select').focus();
  // Focus trap (simplified — see keyboard navigation tutorial)
}

function closeModal() {
  document.getElementById('settings-modal').hidden = true;
  document.getElementById('modal-backdrop').hidden = true;
  document.querySelector('[onclick="openModal()"]').focus();
}
</script>

// Automated ARIA validation with axe-core
const { axe } = require('axe-core');

async function validateARIA(html) {
  const { JSDOM } = require('jsdom');
  const { window } = new JSDOM(html);
  const results = await axe.run(window.document, {
    runOnly: ['aria']
  });

  console.log(`Found ${results.violations.length} ARIA violations:`);
  results.violations.forEach(v => {
    console.log(`\n[${v.impact}] ${v.help}`);
    console.log(`  ${v.description}`);
    v.nodes.forEach(n => {
      console.log(`  → ${n.target}`);
      console.log(`    Fix: ${n.failureSummary}`);
    });
  });
}

validateARIA(`
  <div role="button">Click me</div>
  <div role="tab">Tab 1</div>
  <div role="tabpanel">Content</div>
`);

<div class="rating" role="radiogroup" aria-label="Rate this product">
  <span role="radio" aria-checked="false" aria-label="1 star" tabindex="0"
        data-value="1" onclick="setRating(1)" onkeydown="handleRatingKey(event, 1)">★</span>
  <span role="radio" aria-checked="false" aria-label="2 stars" tabindex="-1"
        data-value="2" onclick="setRating(2)" onkeydown="handleRatingKey(event, 2)">★</span>
  <span role="radio" aria-checked="false" aria-label="3 stars" tabindex="-1"
        data-value="3" onclick="setRating(3)" onkeydown="handleRatingKey(event, 3)">★</span>
  <span role="radio" aria-checked="false" aria-label="4 stars" tabindex="-1"
        data-value="4" onclick="setRating(4)" onkeydown="handleRatingKey(event, 4)">★</span>
  <span role="radio" aria-checked="false" aria-label="5 stars" tabindex="-1"
        data-value="5" onclick="setRating(5)" onkeydown="handleRatingKey(event, 5)">★</span>
</div>
<p aria-live="polite" id="rating-output">No rating selected</p>

<script>
let currentRating = 0;

function setRating(value) {
  currentRating = value;
  document.querySelectorAll('[role="radio"]').forEach((radio, index) => {
    const checked = index < value;
    radio.setAttribute('aria-checked', checked);
    radio.setAttribute('aria-label', `${index + 1} ${index === 0 ? 'star' : 'stars'}`);
  });
  document.getElementById('rating-output').textContent =
    `You rated this ${value} ${value === 1 ? 'star' : 'stars'}`;
}

function handleRatingKey(event, value) {
  if (event.key === ' ' || event.key === 'Enter') {
    event.preventDefault();
    setRating(value);
  }
}
</script>