ARIA attributes

What are ARIA attributes?

ARIA attributes are the states and properties defined by the Web Accessibility Initiative's Accessible Rich Internet Applications (WAI-ARIA) specification, part of the World Wide Web Consortium's accessibility standards. They give assistive technologies extra information about an element – its name, description, or current condition – when native HTML semantics alone don't cover it. Every ARIA attribute starts with the aria- prefix, such as aria-label or aria-expanded.

At a glance

Why are ARIA attributes important when it comes to accessibility?

Screen readers and other assistive technologies don't see a web page the way sighted users do. They work from the accessibility tree: a structured version of the page built from HTML elements, ARIA roles, and ARIA attributes.

If that tree is missing information, screen reader users and people with visual impairments lose context that sighted users get from layout and color.

ARIA attributes fill those gaps.

A descriptive label on an icon-only button, a current state on a toggle, a live region on a status message – all of these depend on ARIA attributes being present and accurate. Without them, interactive components can look fine on screen while being confusing or unusable with a keyboard and a screen reader.

ARIA attributes and web development

ARIA attributes are an important consideration for modern web development teams. As more of a web application's behavior becomes dependent on JavaScript, fewer of its states live in native HTML elements that assistive technologies automatically understand.

Often, ARIA attributes are the only way to improve accessibility for those custom, scripted parts of a page.

Correctly implementing ARIA also helps you stay compliant with the ADA and other regulations. Most accessibility standards, including WCAG, require interactive elements to communicate their name, role, and value to assistive technologies. ARIA attributes usually make that happen.

It’s essential for your team to get this right in order to enhance web accessibility and prevent your users from encountering accessibility issues.

ARIA attributes help web developers who are building modern web applications make their websites usable by everyone – especially those who rely on a screen reader or navigate by keyboard alone.

These attributes are most effective when they are one part of a proactive approach built in from the start of a project, rather than patched onto a web application after it ships. Teams that treat accessibility as a late-stage fix tend to leave gaps that ARIA attributes can't close.

How do ARIA attributes work?

An ARIA attribute sits directly in the HTML markup, on the same element it describes. The browser reads it, along with any ARIA role, native HTML semantics, and the element's content, and exposes the result through the accessibility tree.

Assistive technologies read from that tree, not from the visual page, so an ARIA attribute is only useful if the browser actually exposes it correctly.

ARIA attributes can be split into two broad groups:

• States describe a visual state that changes, usually via JavaScript, as the user interacts with the page. aria-expanded, aria-checked, and aria-pressed are states – a button's aria-expanded attribute flips between true and false as a user input opens or closes a panel.
• Properties describe something more stable about an element, like its name or its relationship to other elements. aria-label and aria-required are properties – they rarely change after the page loads.

The ARIA attributes that apply to an element depend on the role that element has and whether that role comes from native HTML semantics or an explicit role attribute.

A checkbox role expects a corresponding ARIA attribute for its checked state; a dialog role expects one that supplies its accessible name.

Applying an attribute that a role doesn't support, or skipping one it requires, breaks the name, role, and value semantics that screen readers rely on. Make sure you check this when auditing ARIA implementation on an existing page.

Native HTML elements like a <button> or <input> come with accessibility features built into their semantic HTML meaning. For example, a <button> is focusable and operable using only the keyboard, with no extra markup needed.

ARIA attributes are for cases where native HTML elements don’t provide the accessibility information you need, such as custom UI components, non-semantic <div>-based widgets, and parts of a user interface that change after a web page has loaded.

To understand ARIA roles and attributes together, think of the role as the noun and the attributes as everything that qualifies it – both get encoded directly into the web content a browser hands to assistive technologies, so other assistive tools and other tools built on top of the same accessibility APIs can read them consistently.

Common ARIA attributes

• aria-label – Gives an element a descriptive label when there's no visible text to serve as one, such as an icon-only button.
• aria-labelledby – Points to another element's ID to use as the label, making it useful when visible text already exists elsewhere on the page.
• aria-describedby – Points to an element that gives additional description, beyond the name, such as help text next to a form field.
• aria-hidden – Hides an element and its children from the accessibility tree, without hiding it visually. Use it carefully; hiding content that's still reachable by keyboard creates a confusing experience for screen reader users navigating with only the keyboard.
• aria-expanded – Reports whether a collapsible interactive element, like a disclosure button or a menu, is open or closed.
• aria-checked – Reports the checked state of a checkbox-like widget, including a mixed state for partially checked groups.
• aria-controls – Identifies which element an interactive element controls, such as a tab controlling the panel it displays.
• aria-required – Marks one of a page's form elements as required before submission, for assistive technologies that can't always infer this from HTML attributes alone.
• aria-live – Marks a region of dynamic content so updates, like an important message or a status banner, are announced automatically without changing focus.

An ARIA attributes example

A common use for ARIA attributes is to make a custom dialog box accessible – for example, when your design system or CMS components don't use the native HTML <dialog> element. Here's a simplified example:‍

<button aria-controls="confirm-dialog">
  Delete item
</button>

<div
  id="confirm-dialog"
  role="dialog"
  aria-modal="true"
  aria-labelledby="dialog-title"
  aria-describedby="dialog-desc"
  hidden
>
  <h2 id="dialog-title">Delete this item?</h2>
  <p id="dialog-desc">This action can't be undone.</p>
  <button>Cancel</button>
  <button>Delete</button>
</div>

‍The role="dialog" tells assistive technologies what the element is. The ARIA attributes around it fill in the rest: aria-labelledby and aria-describedby supply the dialog's accessible name and descriptive label from existing HTML elements, and aria-controls on the trigger button connects it to the dialog it opens.

The role="dialog" tells assistive technologies what the element is, and aria-modal="true" tells them the rest of the page is off-limits while it's open.

The other ARIA attributes fill in the details: aria-labelledby and aria-describedby provide the dialog's accessible name and description from existing HTML elements, and aria-controls on the trigger button connects it to the dialog it opens.

On a live site, you'd also need JavaScript to show the dialog, move focus into it, and return focus to the button when it closes. ARIA describes how the dialog should behave, but it doesn't make it behave that way.

ARIA attributes vs. ARIA roles

ARIA roles and attributes are often mentioned together, but they do different jobs in the accessibility tree.

A role tells you what an interactive element is and how it behaves. The corresponding ARIA attributes provide specific conditions and context – whether it's expanded, what it's labeled, and what it describes.

An ARIA role without its required attributes tells assistive technologies what something is, without saying anything about its current condition, which is often just as important to a screen reader user.

If a native HTML element already provides the role, states, and behavior you need, use native HTML instead of rebuilding it with role attributes and ARIA attributes. A native <button> element already has a button role, keyboard interaction, and focus handling built in. A <div> with role="button" and a pile of ARIA attributes only recreates part of that, and still needs JavaScript for the rest.

Landmark roles, like navigation or banner, describe structure once, while any ARIA attributes nearby – a current-page indicator or a label distinguishing two navigation regions, for example – describe detail on top of that structure.

Use ARIA and native HTML as complementary skills.

Common mistakes or misconceptions

• Adding an attribute without checking its role. Not every ARIA attribute is valid on every role. An attribute that doesn't correspond to an element's role, or a role attribute used without the ARIA states or properties it requires, produces invalid combinations that confuse assistive tools rather than helping them.
• Hiding focusable content with aria-hidden. Setting aria-hidden="true" on an element that's still reachable by keyboard leaves a screen reader user unable to perceive something they can still tab into. Always remove the element from the tab order first, or avoid hiding it at all.
• Using ARIA attributes before native HTML. It's tempting to patch a non-semantic <div> with role and ARIA attributes instead of using native HTML elements that already have the right native semantics. However, it usually means more code, more chances for error, and a worse result than just using the right HTML element.
• Leaking information through labels. A descriptive label or description meant for internal use, added via aria-label or aria-describedby, is exposed to any assistive technology reading the page. Treat those attributes as user-facing content, not internal notes.
• Letting state attributes go stale. A state like aria-expanded or aria-checked has to be updated by JavaScript every time the underlying UI component changes. If the script only updates the visual state and forgets the attribute, screen reader users hear information that no longer matches what's on screen.
• Assuming one test proves it's implemented correctly. Screen readers, braille displays, switch devices, and other assistive tools don't always announce the same ARIA attributes in an identical way. A component that works well in one combination isn't guaranteed to work everywhere, so testing with more than one tool is important when it comes to components users depend on.
• Treating ARIA as a checklist instead of a best-practices mindset. To follow WAI-ARIA best practices, you need to understand why an attribute is there, not just copy markup from somewhere else. A pasted attribute that doesn't match the actual component behavior is often worse than no attribute at all.