ARIA Role Reference

The ARIA Roles Reference is a comprehensive guide to WAI-ARIA (Web Accessibility Initiative - Accessible Rich Internet Applications) roles, states, and properties. ARIA attributes help screen readers and assistive technology understand web page structure and UI component behavior beyond what HTML alone conveys. Web developers building accessible applications use ARIA to label custom controls (not using native buttons), announce dynamic content changes, structure complex widgets (comboboxes, tabs, dialogs), and fix accessibility gaps in existing sites.

The reference groups ARIA by category: landmark roles (main, navigation, banner), document structure (article, heading, list), widget roles (button, checkbox, combobox, tab, dialog), window roles (alert, log, status), states (aria-expanded, aria-checked, aria-disabled), and properties (aria-label, aria-labelledby, aria-describedby, aria-live). Each entry shows usage examples, screen reader behavior, common mistakes, and links to WAI-ARIA Authoring Practices. Use for accessibility audits, adding ARIA to custom components, or understanding unfamiliar ARIA attributes in existing code.

WAI-ARIA is a W3C standard (current 1.2) defining ways to make web content accessible to users with disabilities, particularly those using screen readers. It supplements HTML with additional semantic information.

Core ARIA concepts:

Role: what the element is (button, heading, listbox)
State: current state (expanded, checked, disabled) — changes during interaction
Property: feature that doesn\u2019t change (label, level, description)

Landmark roles: structural sections of a page
- banner: site header
- navigation: nav menu
- main: main content
- complementary: sidebar
- contentinfo: footer
- search: search area
- region: generic landmark with aria-label

HTML5 equivalents often preferred: <header>, <nav>, <main>, <aside>, <footer>, <form role=\"search\">.

Widget roles: interactive components
- button: clickable action
- checkbox: toggle
- combobox: dropdown with text entry
- dialog: modal dialog
- listbox: select list
- menu/menuitem: application menus
- progressbar: progress indicator
- slider: range input
- tab/tablist/tabpanel: tabbed interface
- tooltip: hover/focus help

Document structure: article, heading, list, table, definition, group, region.

Window-like roles: alert (urgent message), alertdialog (alert + dialog), log (continuous updates), status (status updates), timer.

States (change during interaction):
- aria-busy: currently loading
- aria-checked: checkbox/radio state (true, false, mixed)
- aria-disabled: disabled (alternative to native disabled attribute)
- aria-expanded: collapsible state (true, false)
- aria-hidden: hidden from assistive tech
- aria-pressed: toggle button state
- aria-selected: selected in a set (true, false)

Properties (static):
- aria-label: accessible name when visible text isn\u2019t enough
- aria-labelledby: reference to labelling element(s) by ID
- aria-describedby: reference to description element
- aria-current: current page/step/etc.
- aria-level: heading level for generic role
- aria-live: announces dynamic changes (off, polite, assertive)
- aria-atomic: announce entire live region or just changes
- aria-haspopup: indicates popup (menu, listbox, dialog, etc.)
- aria-controls: what element is controlled

First rule of ARIA: use HTML native semantics when possible. <button>Submit</button> is better than <div role=\"button\" tabindex=\"0\">Submit</div>.

Second rule of ARIA: don\u2019t change HTML semantics unless necessary. Don\u2019t add role=\"button\" to a heading.

Third rule of ARIA: all interactive ARIA controls must be keyboard accessible.

Fourth rule of ARIA: don\u2019t use role=\"presentation\" or aria-hidden=\"true\" on visible focusable elements — it hides from assistive tech but remains interactive.

Fifth rule: all interactive elements must have an accessible name (from visible text, aria-label, aria-labelledby, or title attribute).

Compared to the official WAI-ARIA specification, this reference is more readable and includes practical examples. The spec is authoritative and more complete; this reference is a friendly entry point.

Compared to WAI-ARIA Authoring Practices Guide, this tool provides quick-reference lookups while APG offers detailed pattern implementations. Use APG for building complex widgets; use this tool for quick lookups.

Compared to accessibility testing tools (axe, WAVE), this tool is for learning and reference. Testing tools find issues; this tool helps you understand how to fix them.