ARIA Roles — Widget, Composite, Document and Landmark Roles

In this tutorial, you will learn about ARIA Roles. We cover key concepts, practical examples, and best practices to help you master this topic.

ARIA roles define what an element represents to assistive technologies, with categories including widget, Composite, document structure, landmark, and live region roles.

In this tutorial, you'll learn about ARIA role categories and how to apply them correctly in ARIA implementations.

What You'll Learn

By the end of this lesson, you'll understand the five ARIA role categories, the difference between abstract and concrete roles, which roles require specific owned elements, and how roles interact with the Accessibility tree.

Why It Matters

Choosing the correct role is the foundation of ARIA. The wrong role misleads screen readers and can make your widget unusable.

Real-World Use

Doda Browser's component library uses widget roles for custom buttons, composite roles for tab panels, and landmark roles for page structure.

ARIA Role Categories

flowchart TD
  A[ARIA Roles] --> B[Widget Roles]
  A --> C[Composite Roles]
  A --> D[Document Structure]
  A --> E[Landmark Roles]
  A --> F[Live Region Roles]
  B --> G[button, checkbox, radio]
  C --> H[tablist, menubar, grid]
  D --> I[article, section, heading]
  E --> J[banner, main, navigation]
  F --> K[alert, log, status]

Widget Roles

Widget roles represent standalone interactive elements. They must be focusable and support keyboard interaction.

<div role="button" tabindex="0" onclick="scan()">
  Start Scan
</div>

Common widget roles: button, checkbox, radio, link, menuitem, tab, switch, slider, progressbar.

Composite Roles

Composite roles are widgets that contain other widgets. They manage focus within the group using roving tabindex or aria-activedescendant.

<div role="tablist" aria-label="Scan options">
  <button role="tab" tabindex="0" aria-selected="true">Quick</button>
  <button role="tab" tabindex="-1" aria-selected="false">Full</button>
</div>

Common composite roles: tablist, menubar, grid, listbox, combobox, radiogroup.

Document Structure Roles

Document structure roles describe the structure of content. They are not inherently interactive but provide semantic meaning.

<article role="article">
  <h2 role="heading" aria-level="2">Scan Complete</h2>
  <section role="region" aria-label="Results">
    <p>No threats found.</p>
  </section>
</article>

Common document structure roles: article, section, heading, list, listitem, table, figure.

Landmark Roles

Landmark roles identify major regions of a page, enabling quick navigation for screen reader users.

<header role="banner">
  <nav role="navigation" aria-label="Main">
    <ul><!-- nav links --></ul>
  </nav>
</header>
<main role="main">
  <h1>Dashboard</h1>
</main>
<footer role="contentinfo">
  <p>Copyright 2026 DodaTech</p>
</footer>

Common landmark roles: banner, navigation, main, complementary, contentinfo, form, region.

Live Region Roles

Live region roles tell screen readers to announce content changes without requiring focus.

<div role="alert" aria-live="assertive">
  Scan complete: no threats detected.
</div>

Common live region roles: alert, log, marquee, status, timer.

Common Mistakes

• Using an abstract role: Abstract roles like widget or structure cannot be used directly.
• Mismatched role hierarchy: A menuitem must be inside a menu or menubar.
• Missing owned elements: A tablist should contain tab roles.
• Applying interactive roles to non-focusable elements: A button role without tabindex="0" is not keyboard accessible.
• Using incorrect landmark roles: A <footer> that is not page-level should not have role="contentinfo".

Practice and Challenge

1. What are the five ARIA role categories? Widget, composite, document structure, landmark, and live region roles.

2. What is the difference between widget and composite roles? Composite roles contain other widgets and manage focus within the group.

3. Which role category does role="tab" belong to? Widget role.

4. Can you use role="widget" in HTML? No. Widget is an abstract role used only in the specification.

5. Challenge: Identify the role category for each role in a page's ARIA implementation.

FAQ

Mini Project

Create a page structure using native HTML elements and then add ARIA roles to any elements where the native semantics need supplementing.

What's Next

Continue to ARIA Properties to learn about attributes that describe element characteristics.