What I Wish Someone Told Me When I Was Getting Into ARIA — Smashing Magazine

ARIA Is a Complement to HTML, Not a Replacement

Accessible Rich Internet Applications (ARIA) is something nearly every web developer will encounter eventually. It exists to fill gaps: when HTML alone cannot communicate interactivity, purpose, or state to assistive technology like screen readers and voice control software, ARIA steps in.

Think of ARIA as an enhancement layer. It provides additional information about:

• Interactivity — whether content can be activated or manipulated, such as navigating to a link’s destination.
• Purpose — what something is used for, like a text input collecting a name.
• State — the current status of content, such as an accordion panel being expanded or collapsed.

Consider a mute button as a practical example. The HTML button element tells assistive technology the element is interactive. The visible text “Mute” communicates the button’s purpose. And aria-pressed="true" signals that the button is currently in an active, pushed-in state. Together, these pieces let assistive technology users understand what the element is, what it does, and its current condition.

Why ARIA Looks the Way It Does

ARIA’s first version was published on September 26, 2006. To understand its design, it helps to remember the era. Windows XP was the dominant operating system. The iPhone did not exist yet. Ajax was the cutting-edge approach to building dynamic web experiences, and single-page applications were rare.

ARIA reflects the interaction paradigms of that period. It recreates patterns familiar from operating systems of the time. That has a practical consequence: people who use assistive technology, whether they are older users with muscle memory from those systems or younger users who learned the de facto standards, will likely try Windows-style keyboard shortcuts first when interacting with web content. That means pressing Enter to follow a link, Space to activate a button, and Home or End to jump to the start or end of a list.

This does not mean ARIA is stagnant. The specification is a living document, now at version 1.2 with version 1.3 expected soon. HTML itself continues to evolve to support more app-like experiences. Both efforts are conducted openly, and contribution is possible.

There is an upside to ARIA’s foundation in older interaction patterns. Interactions that cannot be broken down into smaller pieces that map to established ARIA patterns are likely to be inaccessible — and probably confusing to a general audience as well.

The Five Rules of ARIA

ARIA’s official documentation includes five rules that guide its proper use. Observing them will prevent most common mistakes:

1. Prefer native elements. Use an anchor (<a>) for a link rather than a div with a click handler and role="link".
2. Do not override native semantics. Avoid turning a heading into a tab; wrap it in a neutral div instead.
3. Anything interactive must be keyboard operable. If it cannot be used with a keyboard, it is not accessible.
4. Do not hide focusable elements. Never apply role="presentation" or aria-hidden="true" to something that can receive focus.
5. Interactive elements must have accessible names. A button with the text “Print” is properly named.

Understanding Roles, States, and Properties

ARIA has a structured grammar organized around roles, states, and properties. Roles are what assistive technology announces; many people refer to them informally as semantics. HTML elements carry implied roles — an anchor is announced as a link without any additional work. These implied roles are almost always the better choice when they fit the use case, offering stronger guarantees of support across the wide variety of operating systems, browsers, and assistive technology combinations in use.

Roles fall into categories, and one category deserves special attention. Abstract roles exist for organizational purposes within the specification and must never be used by authors in content. Additionally, certain roles have required parent relationships; a listitem role, for instance, requires a list role on its parent element. The official role definitions document these requirements.

While roles describe what an element is, states and properties describe its characteristics in a form assistive technology can understand. States can change in response to human interaction or application logic. When a state changes due to user action, it is considered an unmanaged state, and developers must write the JavaScript to control that interaction. When state changes originate from the application itself — the operating system or browser — it is a managed state, and the platform supplies the underlying logic automatically.

ARIA Syntax And Its Reality Check

ARIA is declared exactly like any other HTML attribute. The specification is a name/value pair system where some values are predefined and others come from you:

For instance, aria-live accepts one of three predefined values (off, polite, and assertive), while aria-label takes whatever text string you supply. Declaring them on an element works the same way as any attribute:

<!-- 
  Applies an id value of 
  "carrot" to the div
-->
<div id="carrot"></div>

<!-- 
  Hides the content of this paragraph 
  element from assistive technology 
-->
<p aria-hidden="true">
  Assistive technology can't read this
</p>

<!-- 
  Provides an accessible name of "Stop", 
  and also communicates that the button 
  is currently pressed. A type property 
  with a value of "button" prevents 
  browser form submission.
-->
<button 
  aria-label="Stop"
  aria-pressed="true"
  type="button">
  <!-- SVG icon -->
</button>

A few usage notes worth remembering:

• Multiple ARIA declarations can live on one element.
• Declaration order doesn't matter, whether among ARIA attributes or alongside others like class and id.
• There's no hard limit on how many you add, but each one increases complexity and the chance that something breaks.

Be aware that HTML's boolean attributes behave differently from ARIA's. Hidde de Vries explains the distinction in his post on boolean attributes in HTML and ARIA.

Most ARIA Is Meant To Be Dynamic

Static, hardcoded ARIA declarations exist, but much of the spec is designed to be applied or modified in response to user actions or application state. A classic example is the disclosure pattern:

• aria-expanded toggles between false and true to convey the expanded or collapsed state.
• The hidden attribute is added or removed in tandem to control the content's visibility.

<div class="disclosure-container">
  <button 
    aria-expanded="false"
    class="disclosure-toggle"
    type="button">
    How we protect your personal information
  </button>
  <div 
    hidden
    class="disclosure-content">
    <ul>
      <li>Fast, accurate, thorough and non-stop protection from cyber attacks</li>
      <li>Patching practices that address vulnerabilities that attackers try to exploit</li>
      <li>Data loss prevention practices help to ensure data doesn't fall into the wrong hands</li>
      <li>Supply risk management practices help ensure our suppliers adhere to our expectations</li>
    </ul>
    <p>
      <a href="https://www.smashingmagazine.com/security/">Learn more about our security best practices</a>.
    </p>
  </div>
</div>

The hardcoded ARIA you'll most often encounter is marking an SVG icon inside a button as decorative:

<button type="button>
  <svg aria-hidden="true">
    <!-- SVG code -->
  </svg>
  Save
</button>

The accessible name "Save" tells assistive technology what the button does when activated. The visual icon supports that understanding for sighted users but adds nothing for screen reader users.

Redundant Roles: Pointless And Historical

Explicitly declaring role="main" on a <main> element does not make it "extra" accessible. The implicit role from semantic HTML is sufficient. Redundant declarations like <main role="main"> or <footer role="contentinfo"> date back to when assistive technology needed a nudge to recognize newer HTML elements.

That stop-gap era is over. Adding redundant roles today is like vendor-prefixing border-radius — unnecessarily cautious and outdated.

Note: An exception exists for complex markup patterns where assistive technology support is unreliable. In such cases, explicitly hardcoding the implicit role can be a deliberate workaround. This is detailed further in the section on unexpected ARIA behavior.

Don't State The Obvious In Accessible Names

Roles, whether implicit or explicit, are announced automatically. You don't need to include the role in a control's text string or its aria-label:

<!-- Don't do this -->
<button 
  aria-label="Save button"
  type="button">
  <!-- Icon SVG -->
</button>

<!-- Do this instead -->
<button 
  aria-label="Save"
  type="button">
  <!-- Icon SVG -->
</button>

An aria-label of "Save button" for a button gets announced as "Save button, button." The repetition is redundant and confusing.

"Menu" Means Something Specific In ARIA

People casually call mega menus and site navigation "menus." In the ARIA spec, a menu has a much narrower meaning — think the Edit menu in an application's menubar, not global navigation.

Misapplying a role because its name sounds right wreaks havoc for assistive technology users. The announced role sets expectations, and when behavior doesn't match, it disorients. Declaring role="menu" on navigation is a common mistake, but not the only one. When in doubt, read the role definitions directly from the specification.

Some Roles Forbid Accessible Names

The following roles cannot take an accessible name: caption, code, deletion, emphasis, generic, insertion, paragraph, presentation, strong, subscript, and superscript. Trying to supply one via aria-label won't work; it's disallowed by ARIA's grammar rules.

<!-- This won't work-->
<strong aria-label="A 35% discount!">
  $39.95
</strong>

<!-- Neither will this -->
<code title="let JavaScript example">
  let submitButton = document.querySelector('button[type="submit"]');
</code>

Browsers sometimes try to override the author-supplied value anyway, creating confusion for everyone. That inconsistency is exactly why this rule exists.

ARIA Is Not A Free-Form Language

Some developers add sketchy CSS classes hoping they'll work, and sometimes they do because those classes already exist in the codebase. ARIA doesn't work that way. The Accessible Rich Internet Applications Working Group predefines the vocabulary, and assistive technology updates to parse it:

<!-- 
  There is no "selectpanel" role in ARIA.
  Because of this, this code will be announced 
  as a button and not as a select panel.
-->
<button 
  role="selectpanel"
  type="button">
  Choose resources
</button>

Invent your own ARIA and assistive technology won't announce it. There is no room for improvisation.

Silent Failure Is The Norm

Malformed ARIA produces no console errors. No alert dialog appears, no warning light flashes, no beep sounds. It just quietly does nothing.

This is a compelling reason to test with actual assistive technology, even if you're not an expert. If you define a state to be announced and your assistive technology doesn't announce it in its default configuration, there's a good chance your code needs fixing.

ARIA Announces; It Does Not Implement

Applying ARIA does not unlock capabilities. It only tells assistive technology how to interpret the content. Declaring role="button" on a div doesn't make that div clickable. You'll still have to:

• Target it in JavaScript,
• Attach a click event handler,
• Implement its interactive logic, and
• Support the other expected keyboard behaviors.

At that point, you might wonder why you didn't just use a real button element in the first place.

Changing a role via ARIA also doesn't alter native functionality. A div with role="image" still won't accept alt or src attributes — those are not supported on div elements.

Semantics Change, Behavior Doesn't

An ARIA role overrides an element's announced semantics but not its built-in behavior. Take an anchor element: its primary capability is navigating to the URL in its href. It also has secondary capabilities — copying the link, opening it in a new tab, and others.

Those secondary capabilities remain intact. However, depending on what gets announced, users may not realize they're available or may be unable to use them as expected. The reverse holds as well: an element without any capabilities gains none from an ARIA role. That's the announcement-only nature of ARIA again — a div with role="button" stays inert without JavaScript.

When You Actually Need ARIA

None of this means ARIA is something to avoid outright. All of this guidance points to one conclusion: use ARIA when HTML cannot describe an interaction natively.

Recognizing those situations starts with a solid understanding of HTML's element vocabulary — what exists and what purposes each element serves. HTML5 Doctor's Element Index is a good place to build that knowledge.

Role and State Pairing Rules

ARIA follows a pattern similar to HTML’s distinction between global attributes and element-specific ones. Some states and properties, like aria-describedby, are valid on virtually any role. Others are restricted. aria-posinset, for instance, only works with article, comment, listitem, menuitem, option, radio, row, and tab roles.

The official ARIA specification documents these constraints in the “Used in Roles” section of each state or property’s characteristics. Automated testing tools — including axe, WAVE, ARC Toolkit, Pa11y, and equal-access — can flag violations when they slip through. Running these checks in continuous integration turns accessibility into a shared code quality concern rather than an afterthought.

Beyond the Browser

ARIA does not communicate directly with assistive technology. The browser translates your ARIA into the accessibility tree and reports it to the operating system. Assistive technology listens to what the operating system reports, then conveys that information to the person using the device. When the person issues a command, the assistive technology asks the operating system to act on the content displayed in the browser.

This layered approach is intentional. It keeps interaction from assistive technology indistinguishable from standard interaction, preserving privacy and autonomy for people who rely on these tools.

Specification Is Not Support

Web developers are accustomed to declaring standards-compliant HTML and expecting consistent behavior across browsers. ARIA does not work that way. Assistive technology vendors implement their own interpretation of the ARIA specification. Interpretations often converge, but not always. Vendors maintain their own roadmaps, and some may add support, some may never, and some may implement features in contradictory ways.

The operating system layer complicates matters further. The mechanisms used to communicate with assistive technology are aging and under-maintained areas of software. A given piece of assistive technology may support your ARIA while the operating system cannot communicate it — or vice versa.

There is no Caniuse or Baseline equivalent for assistive technology. a11ysupport.io is the closest resource, but it is maintained by a single individual and may not be current. Manual testing with real assistive technology remains the only reliable way to verify that your ARIA works as intended.

Three Layers of Support

Whether an ARIA declaration works depends on three variables:

1. Operating system and version.
2. Assistive technology and version.
3. Browser and browser version.

Operating system. Windows, macOS, and Linux each report content to assistive technology differently, and each assistive tool must accommodate those differences. Some combinations are impossible — VoiceOver does not run on Windows, nor JAWS on macOS. OS versions vary in what they report and how. Updates sometimes introduce bugs or regressions in accessibility reporting.

Assistive technology. Each screen reader and assistive tool is built to address different needs with its own heuristics and preferences. Version differences, bugs, and regressions all apply. Two additional human factors matter here: upgrade hesitancy and financial constraints. People who rely on assistive technology may avoid upgrades out of fear of breaking a critical mechanism for interacting with the world. Disabled populations also face lower employment rates and less disposable income, sometimes called the disability or crip tax, affecting their ability to purchase new or updated technology.

Browser. How well a browser exposes content to assistive technology affects compatibility. Some pairings work notably well, such as Firefox with NVDA. Support may only arrive in newer browser versions, and regressions can slip through releases when accessibility is underfunded or deprioritized.

Familiarity Predicts Reliability

Common ARIA declarations — aria-label, aria-labelledby, aria-describedby, aria-hidden, and aria-live — tend to have better support because they have been around longer. More esoteric or historically neglected declarations may lack support or never gain it.

aria-controls illustrates the problem. It has existed for years, yet JAWS removed support after user feedback, and other screen readers never implemented it. Situations like this reinforce why manual testing with assistive technology is the only dependable verification method.

Density Increases Risk

The more ARIA you add to a component, the greater the chance of unexpected behavior. Assistive technology reads what the DOM exposes and interprets intent through nested parent ARIA declarations. Feature-based development that focuses on isolated portions of an experience can overlook these holistic interactions.

WebAIM’s annual analysis of the top one million websites found a correlation between increased ARIA usage and higher detected errors:

Increased ARIA usage on pages was associated with higher detected errors. The more ARIA attributes that were present, the more detected accessibility errors could be expected.

The analysis notes this does not prove ARIA causes the errors — such pages are typically more complex — but the association is consistent.

Invalid ARIA Can Still Work

Inaccurate ARIA occasionally functions as intended with assistive technology. This is not a sound authoring strategy, but it matters for debugging. Some mature assistive technology vendors accommodate authors with limited ARIA familiarity to ensure their users can still access content. There is no exhaustive list of these accommodations, but the behavior parallels how browsers intentionally forgive malformed HTML to prioritize rendering content for humans.

Accessible Names Come With Caveats

aria-label is everywhere in ARIA code — and it’s also one of the most misused declarations. It cannot be applied to non-interactive HTML elements, yet often is. It isn’t always translated, and it frequently gets left out of localization workflows. Voice control users can also hit problems when the visible label on screen doesn’t match what assistive technology announces.

There’s also the issue of aria-label overriding an element’s existing accessible name. Using it that way violates WCAG Success Criterion 2.5.3: Label in Name. The same goes for using aria-label to smuggle in control hints for screen readers — another WCAG failure and an antipattern. All of this is why it’s fair to treat aria-label as a code smell rather than a default tool.

Live Regions and the APG Both Need Scrutiny

aria-live is the mechanism behind screen reader announcements of dynamic content updates. Getting it right is genuinely difficult even in ideal conditions, so rather than rehashing implementation details here, it’s worth reading TetraLogical’s comprehensive “Why are my live regions not working?” for the specifics.

The ARIA Authoring Practices Guide (APG) similarly deserves a cautious approach. Its examples overwhelmingly favor ARIA-heavy solutions, which makes sense historically — the guide was written to demonstrate what ARIA can do. But its recent redesign makes it look far more approachable than the surrounding W3C documentation, and its pattern demos read like drop-in code. That impression is misleading.

Just because something appears in the spec — or the APG — doesn’t mean assistive technology supports it. Adrian Roselli goes into depth on this topic in “No, APG’s Support Charts Are Not ‘Can I Use’ for ARIA.” And recall that the first rule of ARIA says not to use it when native HTML works; an ARIA-first approach runs counter to the spec’s own philosophy.

The practical fallout of treating APG examples as ready-to-use code usually lands in three places:

• Accessibility practitioners have to explain why “doing the right thing” from the docs won’t work as written.
• Developers must revisit and rework their implementation.
• Assistive technology users risk ending up with an inaccessible experience.

That doesn’t account for the collateral damage to timelines, relationships and team reputation. But the APG isn’t without value. Its strongest contribution is documenting the keyboard behavior users expect from each pattern. The listbox pattern, for instance, spells out arrow key, Space and Enter handling — along with less obvious expectations like typeahead and multi-select. Since ARIA’s interaction model descends from Windows XP-era conventions, people approach your tree view or menu with the muscle memory those legacy patterns built. Meeting those expectations keeps things intuitive.

The APG also gives teams standardized names for UI patterns, which clears up ambiguity around terms like dropdown, listbox, combobox and select menu. When those words carry specific technical meanings, having a common vocabulary makes design and maintenance discussions far more productive.

macOS VoiceOver Is a Trap

VoiceOver on macOS has become increasingly unreliable over the last several years, and it’s tempting to treat it as the default test target since most web development happens on Macs. But macOS VoiceOver holds a minority share of desktop screen reader usage — under 10 percent — while Windows-based JAWS and NVDA together account for about 78 percent. Testing only with VoiceOver means testing for the wrong audience.

The current state of macOS VoiceOver has enough problems that it should only be used to confirm an experience works the way Windows screen readers handle it. A far better workflow is:

1. Build the underlying markup first.
2. Test with NVDA or JAWS to establish baseline behavior.
3. Test with macOS VoiceOver to catch the gaps.

In practice, that often means declaring redundant ARIA roles on already-semantic HTML just to get the announcements macOS VoiceOver misses. It’s still worth doing — macOS VoiceOver users deserve a working experience — but treat it as a compatibility check, not the source of truth.

To run Windows tools from macOS, options include VirtualBox with Windows evaluation VMs or on-demand services like AssistivLabs. And note that iOS VoiceOver is a completely separate product from its macOS namesake, with its own behavior and an overwhelming 70.6 percent share of mobile screen reader usage. Mobile ARIA deserves its own testing.

ARIA Works With CSS and Tests

ARIA attributes are styleable just like any other HTML attribute. Take a navigation section with aria-current="true" on the current page’s link — assistive technology will announce it as the current location. That same attribute can drive visible styling via CSS, which makes it a clean way to tie application state to what users see. Combined with modern CSS features like :has() and view transitions, you can build sophisticated interfaces without reaching for JavaScript.

ARIA declarations are also useful allies in UI testing. Tests that latch onto presentation classes like .is-expanded or data attributes are more likely to break when markup changes. Semantic selectors are sturdier. As Cam McHenry points out in his post on writing accessible Playwright tests, selecting by aria-expanded and role — what the UI is doing — rather than appearance gives you targeted, long-lasting tests. That approach rewards keeping semantic HTML and ARIA in your front-end code, which protects accessible experiences from regressions over time. Paired with styling driven by the same attributes, you end up with a solid system for building experiences that stay accessible.

Accessibility Is People, Not Specifications

Web accessibility enables everything from booking a medical appointment to chatting with friends — and every experience in between. Semantic HTML, supplemented with carefully authored ARIA, is what makes those experiences possible.

Taking a step back, ARIA:

• Was created in an era whose spirit still shapes it today;
• Has a defined taxonomy, vocabulary, and usage rules, declared like any HTML attribute;
• Serves primarily dynamic, JavaScript-controlled content updates;
• Assigns highly specific roles for each use case;
• Fails silently when misused;
• Only signals existence to assistive technology — it does not add interactivity;
• Relies on browser and operating system cooperation before assistive technology can act;
• Varies in real-world support, especially with increasing complexity;
• Has caveats worth remembering, including aria-label, the ARIA Authoring Practices Guide, and macOS VoiceOver quirks;
• Can also support visual styling and resilient testing;
• Is best judged through hands-on testing with actual assistive technology.

From one angle, ARIA feels obscure, overrun with misconceptions, and easy to misuse. From another, it is an elegant, structured system for communicating a user interface’s state and interactivity.

The latter view is the one that matters. Ultimately, the point of ARIA is to make sure disabled people experience the web in the same way everyone else does.

Thanks to Adrian Roselli and Jan Maarten for their feedback.

Further Reading

• What the Heck is ARIA? A Beginner’s Guide to ARIA for Accessibility, Kat Shaw
• Accessibility APIs: A Key To Web Accessibility, Léonie Watson & Chaals McCathie Nevile
• Semantics to Screen Readers, Melanie Richards
• What ARIA does not do, Steve Faulkner
• What ARIA still does not do, stevef
• APG support tables — why they matter, Michael Fairchild
• ARIA vs HTML, Adrian Roselli

ARIA Is Ultimately About Caring About People

Web accessibility can be about enabling important things like scheduling medical appointments. It is also about fun things like chatting with your friends. It’s also used for every web experience that lives in between.

Using semantic HTML — supplemented with a judicious application of ARIA — helps you enable these experiences. To sum things up, ARIA:

• Has been around for a long time, and its spirit reflects the era in which it was first created;
• Has a governing taxonomy, vocabulary, and rules for use and is declared in the same way HTML attributes are;
• Is mostly used for dynamically updating things, controlled via JavaScript;
• Has highly specific use cases in mind for each of its roles;
• Fails silently if mis-authored;
• Only exposes the presence of something to assistive technology and does not confer interactivity;
• Requires input from the web browser, but also the operating system, in order for assistive technology to use it;
• Has a range of actual support, complicated by the more of it you use;
• Has some things to watch out for, namely aria-label, the ARIA Authoring Practices Guide, and macOS VoiceOver support;
• Can also be used for things like visual styling and writing resilient tests;
• Is best evaluated by using actual assistive technology.

Viewed one way, ARIA is arcane, full of misconceptions, and fraught with potential missteps. Viewed another, ARIA is a beautiful and elegant way to programmatically communicate the interactivity and state of a user interface.

I choose the second view. At the end of the day, using ARIA helps to ensure that disabled people can use a web experience the same way everyone else can.

Thank you to Adrian Roselli and Jan Maarten for their feedback.

Further Reading

• What the Heck is ARIA? A Beginner’s Guide to ARIA for Accessibility, Kat Shaw
• Accessibility APIs: A Key To Web Accessibility, Léonie Watson & Chaals McCathie Nevile
• Semantics to Screen Readers, Melanie Richards
• What ARIA does not do, Steve Faulkner
• What ARIA still does not do, stevef
• APG support tables — why they matter, Michael Fairchild
• ARIA vs HTML, Adrian Roselli