The Complete A11y Reference

<!-- Good: landmark regions give structure -->
<header>
  <nav aria-label="Main navigation">
    <ul>
      <li><a href="/">Home</a></li>
      <li><a href="/about">About</a></li>
    </ul>
  </nav>
</header>

<main id="main-content">
  <article>
    <h1>Page title</h1>
    <section aria-labelledby="section-heading">
      <h2 id="section-heading">Section title</h2>
      <p>Content...</p>
    </section>
  </article>
</main>

<footer>
  <p>&copy; 2025 Company</p>
</footer>

<!-- Bad: skipping heading levels -->
<h1>Page title</h1>
<h3>Section</h3>   <!-- jumped from h1 to h3 -->

<!-- Good: logical hierarchy -->
<h1>Page title</h1>
  <h2>Section</h2>
    <h3>Subsection</h3>
  <h2>Another section</h2>

<!-- Bad: div used as button -->
<div onclick="submit()">Submit</div>

<!-- Good: use the native element -->
<button type="submit">Submit</button>

<!-- If you MUST use a div as a button -->
<div role="button" tabindex="0"
     onkeydown="if(e.key==='Enter'||e.key===' ')submit()"
     onclick="submit()">
  Submit
</div>

<!-- HTML5 elements map to landmark roles automatically -->
<header>     <!-- role="banner" (only when top-level) -->
<nav>        <!-- role="navigation" -->
<main>       <!-- role="main" -->
<aside>      <!-- role="complementary" -->
<footer>     <!-- role="contentinfo" (only when top-level) -->
<section>    <!-- role="region" only when given a label -->

<!-- When you have multiple navs, label them -->
<nav aria-label="Main navigation">...</nav>
<nav aria-label="Breadcrumb">...</nav>
<nav aria-label="Pagination">...</nav>

<!-- Section needs a label to become a landmark -->
<section aria-labelledby="news-heading">
  <h2 id="news-heading">Latest news</h2>
</section>

<!-- Widget roles -->
<div role="button">        <!-- interactive button -->
<div role="checkbox">      <!-- checkable item -->
<div role="combobox">      <!-- editable dropdown -->
<div role="listbox">       <!-- list of selectable options -->
<div role="menu">          <!-- context/action menu -->
<div role="menuitem">      <!-- item in a menu -->
<div role="option">        <!-- option in a listbox/combobox -->
<div role="progressbar">   <!-- progress indicator -->
<div role="switch">        <!-- toggle on/off -->
<div role="tab">           <!-- a tab in a tablist -->
<div role="tablist">       <!-- container of tabs -->
<div role="tabpanel">      <!-- content for a tab -->
<div role="tooltip">       <!-- tooltip -->

<!-- Document roles -->
<div role="alert">         <!-- urgent message (assertive) -->
<div role="dialog">        <!-- modal or non-modal dialog -->
<div role="status">        <!-- non-urgent status message -->

<!-- Labelling -->
<button aria-label="Close dialog">✕</button>
<input aria-labelledby="label-id">
<input aria-describedby="help-text-id">

<!-- State -->
<button aria-expanded="false">Show more</button>
<div aria-hidden="true">Decorative, hidden from AT</div>
<li role="option" aria-selected="true">Option A</li>
<input type="checkbox" aria-checked="mixed"> <!-- indeterminate -->
<button aria-disabled="true">Can't do this</button>
<input aria-required="true">
<input aria-invalid="true" aria-describedby="err">
<span id="err" role="alert">Required field</span>

// Dynamic update in JS
const btn = document.querySelector('#toggle');
btn.addEventListener('click', () => {
  const expanded = btn.getAttribute('aria-expanded') === 'true';
  btn.setAttribute('aria-expanded', !expanded);
  document.getElementById('panel').hidden = expanded;
});

<!-- tabindex="0" — add to tab order (natural DOM position) -->
<div role="button" tabindex="0">Custom button</div>

<!-- tabindex="-1" — focusable by script, not by Tab -->
<div id="panel" tabindex="-1">Dialog panel</div>

<!-- tabindex="1+" — AVOID. Forces unnatural tab order -->
<button tabindex="3">Don't do this</button>

// Handle both Enter and Space for custom buttons
element.addEventListener('keydown', (e) => {
  if (e.key === 'Enter' || e.key === ' ') {
    e.preventDefault();
    handleAction();
  }
});

// Arrow key navigation in a menu
const items = menu.querySelectorAll('[role="menuitem"]');
let currentIndex = 0;

menu.addEventListener('keydown', (e) => {
  if (e.key === 'ArrowDown') {
    e.preventDefault();
    currentIndex = (currentIndex + 1) % items.length;
    items[currentIndex].focus();
  }
  if (e.key === 'ArrowUp') {
    e.preventDefault();
    currentIndex = (currentIndex - 1 + items.length) % items.length;
    items[currentIndex].focus();
  }
  if (e.key === 'Escape') closeMenu();
});

/* Good: visible and branded focus styles */
:focus-visible {
  outline: 3px solid #1746a2;
  outline-offset: 3px;
  border-radius: 3px;
}

/* For dark backgrounds */
.dark-bg:focus-visible {
  outline: 3px solid #fff;
  box-shadow: 0 0 0 5px #1746a2;
}

function trapFocus(element) {
  const focusable = [...element.querySelectorAll(
    'a[href], button:not([disabled]), textarea, input, select, [tabindex]:not([tabindex="-1"])'
  )];
  const first = focusable[0];
  const last = focusable[focusable.length - 1];

  element.addEventListener('keydown', (e) => {
    if (e.key !== 'Tab') return;
    if (e.shiftKey) {
      if (document.activeElement === first) {
        last.focus(); e.preventDefault();
      }
    } else {
      if (document.activeElement === last) {
        first.focus(); e.preventDefault();
      }
    }
  });
}

<!-- First element in <body> -->
<a href="#main-content" class="skip-link">Skip to main content</a>

<!-- The target must be focusable -->
<main id="main-content" tabindex="-1">
  <h1>Page title</h1>
</main>

.skip-link {
  position: absolute;
  top: -100%;
  left: 1rem;
  padding: .5rem 1rem;
  background: #1746a2;
  color: #fff;
  font-weight: 600;
  border-radius: 0 0 8px 8px;
  z-index: 9999;
  transition: top 0.15s;
}
.skip-link:focus { top: 0; }

<!-- Method 1: explicit label (preferred) -->
<label for="email">Email address</label>
<input type="email" id="email" name="email">

<!-- Method 2: wrapping label -->
<label>
  Email address
  <input type="email" name="email">
</label>

<!-- Method 3: aria-label (when no visible label) -->
<input type="search" aria-label="Search products">

<!-- Placeholder is NOT a label -->
<input placeholder="Email"> <!-- bad alone — pair with a label -->

<!-- Required fields + error state -->
<label for="name">
  Full name <span aria-hidden="true">*</span>
</label>
<input type="text" id="name" required aria-required="true"
       aria-invalid="true" aria-describedby="name-error">
<p id="name-error" role="alert">This field is required</p>

<!-- Group related inputs -->
<fieldset>
  <legend>Notification preferences</legend>
  <label><input type="checkbox" name="email-notify"> Email</label>
  <label><input type="checkbox" name="sms-notify"> SMS</label>
</fieldset>

<!-- Meaningful image: describe purpose, not appearance -->
<img src="logo.png" alt="a11ytest.ai">

<!-- Decorative image: empty alt suppresses from screen readers -->
<img src="decoration.svg" alt="">

<!-- Functional image (inside a link): describe destination -->
<a href="/dashboard">
  <img src="icon-dashboard.svg" alt="Dashboard">
</a>

<!-- Complex image: use figcaption for long description -->
<figure>
  <img src="chart.png"
       alt="Sales chart for Q3 2025"
       aria-describedby="chart-desc">
  <figcaption id="chart-desc">
    Line chart showing revenue growing from £120k in July
    to £180k in September.
  </figcaption>
</figure>

<!-- Inline SVG: use title + desc -->
<svg role="img" aria-labelledby="svg-title svg-desc">
  <title id="svg-title">Upload progress</title>
  <desc id="svg-desc">65% of file uploaded</desc>
</svg>

<!-- Decorative SVG: hide completely -->
<svg aria-hidden="true" focusable="false">...</svg>

<!-- aria-live="polite": announces after user is idle -->
<div aria-live="polite" aria-atomic="true" id="status"></div>

<!-- role="status" = polite live region (shorthand) -->
<div role="status">3 results found</div>

<!-- role="alert" = assertive, interrupts immediately -->
<div role="alert">Error: session expired</div>

function announce(message, priority = 'polite') {
  const el = document.createElement('div');
  el.setAttribute('aria-live', priority);
  el.setAttribute('aria-atomic', 'true');
  el.style.cssText = 'position:absolute;width:1px;height:1px;overflow:hidden;clip:rect(0,0,0,0)';
  document.body.appendChild(el);
  setTimeout(() => { el.textContent = message; }, 100);
  setTimeout(() => { el.remove(); }, 5000);
}

announce('Form submitted successfully');
announce('Error: email already in use', 'assertive');

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

<div role="dialog"
     id="my-modal"
     aria-modal="true"
     aria-labelledby="modal-title"
     aria-describedby="modal-desc"
     hidden>
  <h2 id="modal-title">Confirm deletion</h2>
  <p id="modal-desc">This action cannot be undone.</p>
  <button type="button" id="confirm-btn">Delete</button>
  <button type="button" id="cancel-btn">Cancel</button>
  <button type="button" aria-label="Close dialog">✕</button>
</div>

const modal = document.getElementById('my-modal');
let previousFocus;

function openModal() {
  previousFocus = document.activeElement;  // remember trigger
  modal.hidden = false;
  modal.querySelector('button').focus();   // move focus in
  document.addEventListener('keydown', handleEscape);
}

function closeModal() {
  modal.hidden = true;
  document.removeEventListener('keydown', handleEscape);
  previousFocus?.focus();                  // return focus to trigger
}

function handleEscape(e) {
  if (e.key === 'Escape') closeModal();
}

<div role="tablist" aria-label="Account settings">
  <button role="tab"
          id="tab-profile"
          aria-controls="panel-profile"
          aria-selected="true"
          tabindex="0">
    Profile
  </button>
  <button role="tab"
          id="tab-security"
          aria-controls="panel-security"
          aria-selected="false"
          tabindex="-1">
    Security
  </button>
</div>

<div role="tabpanel" id="panel-profile" aria-labelledby="tab-profile">
  Profile content...
</div>
<div role="tabpanel" id="panel-security" aria-labelledby="tab-security" hidden>
  Security content...
</div>

const tabs = [...tablist.querySelectorAll('[role="tab"]')];

function activateTab(tab) {
  tabs.forEach(t => {
    t.setAttribute('aria-selected', 'false');
    t.setAttribute('tabindex', '-1');
    document.getElementById(t.getAttribute('aria-controls')).hidden = true;
  });
  tab.setAttribute('aria-selected', 'true');
  tab.setAttribute('tabindex', '0');
  document.getElementById(tab.getAttribute('aria-controls')).hidden = false;
  tab.focus();
}

tablist.addEventListener('keydown', (e) => {
  const i = tabs.indexOf(document.activeElement);
  if (e.key === 'ArrowRight') activateTab(tabs[(i + 1) % tabs.length]);
  if (e.key === 'ArrowLeft')  activateTab(tabs[(i - 1 + tabs.length) % tabs.length]);
});

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

document.querySelectorAll('.accordion button').forEach(btn => {
  btn.addEventListener('click', () => {
    const expanded = btn.getAttribute('aria-expanded') === 'true';
    const panel = document.getElementById(btn.getAttribute('aria-controls'));
    btn.setAttribute('aria-expanded', !expanded);
    panel.hidden = expanded;
  });
});