ARIA Attributes Guide
Accessible Rich Internet Applications — the standard for conveying UI state, roles, and relationships that semantic HTML alone cannot express to assistive technologies.
3 Rules of ARIA Use
HTML first
If semantic HTML can express it, do not use ARIA. A <button> is better than role="button".
Do not change native semantics
Do not override built-in meaning, like <h1 role="button">.
Interactive elements must support keyboard
If you add a role, you must also implement the corresponding keyboard behavior (Enter, Space, Arrow keys, etc.).
Roles (role)
Landmark roles
bannerPage header area. Equivalent to <header>.
navigationNavigation link group. Equivalent to <nav>.
mainPage's primary content. Equivalent to <main>.
complementarySupporting content (like a sidebar). Equivalent to <aside>.
contentinfoPage footer area. Equivalent to <footer>.
regionA named section. Use with aria-label.
Widget roles
dialogModal dialog. Requires aria-modal="true" and focus trapping.
tablist / tab / tabpanelTab UI composition. These three roles work as a set.
comboboxSearch + dropdown combination. Requires aria-expanded and aria-controls.
listbox / optionSelection list. Used for custom <select> implementations.
alertMessage that must be read immediately. Automatically acts as aria-live="assertive".
statusNon-urgent status message. Acts as aria-live="polite".
States and properties (aria-*)
States
aria-expandedIndicates whether an element is expanded. Used for accordions, dropdowns.
aria-checkedIndicates checked state. Values: true / false / mixed.
aria-disabledIndicates disabled state. Unlike disabled, focus is maintained.
aria-selectedIndicates selected state. Used for tabs, listbox options.
aria-pressedIndicates the pressed state of a toggle button.
aria-hiddenCompletely hides from assistive technologies. Used for decorative elements.
Relations
aria-labelProvides an accessible name directly on the element. Used for buttons without visible text.
aria-labelledbyReferences another element by ID to provide a name. Preferred when text is already on screen.
aria-describedbyConnects additional description text. Used for input field error messages and hint text.
aria-controlsReferences the ID of the element this element controls. Tab→panel, button→dropdown.
aria-ownsExpresses a logical ownership relationship that is not a DOM parent-child relationship.
Live regions (aria-live)
aria-live="polite"Reads changes after the current content finishes. Used for search result counts, success messages.
aria-live="assertive"Interrupts and reads changes immediately. Use only for urgent notifications like error messages.
aria-atomic="true"Reads the entire region content when any part changes. Used when full context is needed over partial updates.
aria-relevantSpecifies which changes (additions/removals/text) to announce. Default is additions text.