WAI-ARIA Reference

WAI-ARIA (Web Accessibility Initiative Accessible Rich Internet Applications) is a W3C specification that provides semantic attributes for HTML elements that lack native accessibility semantics. Use ARIA when building custom interactive widgets (carousels, date pickers, custom dropdowns) that cannot be implemented with native HTML elements like <button>, <select>, or <input>. The first rule of ARIA: if you can use a native HTML element with the correct semantics, do so instead.

A visible label (associated with <label for="..."> or wrapping the input) is the preferred approach — it is visible to all users and automatically read by screen readers. aria-label is used when a visible label is not possible or desirable, such as icon buttons that only show a graphic. The aria-label value replaces the element's accessible name entirely, so use aria-labelledby instead if you want to reference an existing visible text element.

role="alert" (equivalent to aria-live="assertive") interrupts the user and reads immediately — use it for critical errors and important warnings that need immediate attention. aria-live="polite" waits for the user to finish current activity before announcing — use it for search result counts, status messages, and non-critical updates. Both work with dynamically injected content in single-page applications.

Apply role="dialog" with aria-modal="true" to the container, use aria-labelledby pointing to the dialog's heading element. When the dialog opens, move keyboard focus to the first focusable element inside and implement a focus trap (Tab and Shift+Tab cycle only within the dialog). When the dialog closes, return focus to the element that triggered it. Add a close button with aria-label="Close dialog".

aria-expanded indicates whether a collapsible element (accordion, dropdown, tree node) is open (true) or closed (false). It is paired with aria-controls pointing to the controlled region. aria-selected indicates which option is currently selected in a multi-item widget like a tablist, listbox, or grid. Unlike checked state, selected state does not toggle — it shows which item is active.

Use a div with role="tablist" containing buttons with role="tab" and aria-selected="true/false". Each tab button should have aria-controls pointing to its corresponding tabpanel div. The active tab has aria-selected="true"; inactive tabs have aria-selected="false". Implement keyboard navigation: Left/Right arrows move between tabs, Home/End jump to first/last, Tab moves into the active tabpanel.

Add tabindex="0" to make a non-interactive element (div, span) focusable and include it in the natural tab order — required when you assign an interactive ARIA role like role="button", role="checkbox", or role="slider" to a non-native element. Use tabindex="-1" to make an element programmatically focusable (via JavaScript focus()) but not reachable via keyboard Tab navigation. Avoid positive tabindex values as they disrupt natural reading order.

aria-hidden="true" removes an element and all its children from the accessibility tree, making them invisible to screen readers. Use it for purely decorative elements (icon fonts, background images, duplicate text), UI chrome that would be confusing to announce (loading spinners adjacent to labeled buttons), and off-screen content that is not logically visible. Never apply aria-hidden to an element that has or contains keyboard focus.