aria-hidden / aria-expanded / aria-live

aria-hidden, aria-expanded, and aria-live are WAI-ARIA attributes used to communicate the visibility state of elements and dynamic content updates to assistive technologies such as screen readers.

Syntax

<!-- aria-hidden: hide from screen readers -->
<span aria-hidden="true">🎉</span>

<!-- aria-expanded: communicate open/closed state -->
<button aria-expanded="false" aria-controls="menu">Menu</button>
<ul id="menu" hidden>...</ul>

<!-- aria-live: notify screen readers of dynamic updates -->
<div aria-live="polite">Loading complete.</div>

<!-- aria-checked: communicate checked state -->
<div role="checkbox" aria-checked="true">Agree</div>

<!-- aria-disabled: communicate disabled state -->
<button aria-disabled="true">Submit</button>

Attribute list

Attribute	Description
aria-hidden	Setting this to `"true"` excludes the element from screen reader output. Use it to hide decorative icons and duplicate content.
aria-expanded	Communicates the current state of collapsible elements such as menus and accordions, using `"true"` (open) or `"false"` (closed).
aria-live	Specifies how dynamically updated content is announced. Accepted values are `"polite"` (announce after the current readout finishes), `"assertive"` (interrupt immediately), and `"off"` (no announcement).
aria-checked	Communicates the checked state of custom checkboxes and radio buttons using `"true"`, `"false"`, or `"mixed"`.
aria-disabled	Setting this to `"true"` indicates that the element is disabled. Unlike the HTML `disabled` attribute, focus and click events are preserved.

Sample code

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
</head>
<body>

  <!-- aria-hidden: exclude decorative icon from screen reader output -->
  <button>
    <span aria-hidden="true">📧</span>
    Send email
  </button>

  <!-- aria-expanded: accordion open/closed state -->
  <button id="toggle" aria-expanded="false" aria-controls="panel">
    Show details
  </button>
  <div id="panel" hidden>
    <p>The detailed content appears here.</p>
  </div>

  <!-- aria-live: announce the result of an async operation -->
  <div id="status" aria-live="polite"></div>

  <script>
    // Toggle the panel and aria-expanded when the button is clicked
    const btn = document.getElementById('toggle');
    const panel = document.getElementById('panel');
    btn.addEventListener('click', () => {
      const isOpen = btn.getAttribute('aria-expanded') === 'true';
      btn.setAttribute('aria-expanded', !isOpen);
      panel.hidden = isOpen;
    });

    // Notify the screen reader when the async operation completes
    setTimeout(() => {
      document.getElementById('status').textContent = 'Data loaded successfully.';
    }, 2000);
  </script>

</body>
</html>

Result

The screen reader skips the 📧 icon and reads "Send email, button." The accordion button is announced as "Show details, collapsed, closed, button," and changes to "open" when clicked. Two seconds later, the status area update is announced as "Data loaded successfully."

<!-- Screen reader announcement example -->
📧 button     → "Send email, button" (icon is skipped)
Accordion     → "Show details, collapsed, closed, button"
After click   → "Show details, collapsed, open, button"
After 2 sec   → "Data loaded successfully." (announced without interrupting)

Notes

aria-hidden="true" removes an element from the screen reader's reading order. Use it on decorative icons, emoji, and duplicate text so that users of assistive technologies are not read unnecessary information. Never place aria-hidden="true" on focusable elements (buttons, links, or inputs). Doing so creates elements that can be reached by keyboard but are invisible to screen readers.

aria-live is intended for content that changes dynamically via JavaScript, such as search results, notification messages, and error displays. The value "polite" waits until the current readout finishes before announcing the update, making it suitable for routine feedback. The value "assertive" interrupts immediately, so reserve it for high-priority cases such as critical error messages — overuse will degrade the user experience.

aria-checked and aria-disabled are used with custom UI components (such as CSS-styled checkboxes). Whenever native HTML — <input type="checkbox"> or the disabled attribute — can handle the requirement, prefer that instead. ARIA is a supplement for cases that cannot be expressed through native HTML semantics. For detailed usage examples of aria-expanded, see also details / summary.

If you find any errors or copyright issues, please contact us.

Home