Complete reference guide to ARIA roles with examples and best practices
Found 31 roles
Site header/banner containing site-wide content
HTML Equivalent: <header> (when direct child of body)
Common Mistakes:
<header role="banner">
<h1>Site Title</h1>
<nav>...</nav>
</header>WCAG 2.1 - 1.3.1 Info and Relationships
Navigation section with links to navigate the site
HTML Equivalent: <nav>
Common Attributes:
aria-labelaria-labelledbyCommon Mistakes:
<nav role="navigation" aria-label="Main Navigation">
<ul>
<li><a href="/">Home</a></li>
</ul>
</nav>WCAG 2.1 - 2.4.1 Bypass Blocks
Main content of the document
HTML Equivalent: <main>
Common Mistakes:
<main role="main" id="main-content">
<h1>Page Title</h1>
<article>...</article>
</main>WCAG 2.1 - 2.4.1 Bypass Blocks
Supporting content related to main content
HTML Equivalent: <aside>
Common Attributes:
aria-labelaria-labelledby<aside role="complementary" aria-label="Related Articles">
<h2>Related</h2>
<ul>...</ul>
</aside>WCAG 2.1 - 1.3.1 Info and Relationships
Footer with metadata about the document
HTML Equivalent: <footer> (when direct child of body)
<footer role="contentinfo">
<p>© 2024 Company</p>
</footer>WCAG 2.1 - 1.3.1 Info and Relationships
Search functionality
Common Attributes:
aria-labelaria-labelledby<div role="search" aria-label="Site Search">
<input type="search" />
<button>Search</button>
</div>WCAG 2.1 - 1.3.1 Info and Relationships
Important content area that users may want to navigate to
Required Attributes:
aria-label or aria-labelledbyCommon Mistakes:
<section role="region" aria-labelledby="section-title">
<h2 id="section-title">Important Section</h2>
</section>WCAG 2.1 - 1.3.1 Info and Relationships
Form landmark when form is significant
HTML Equivalent: <form> (when has accessible name)
Common Attributes:
aria-labelaria-labelledby<form role="form" aria-label="Contact Form">
<label>...</label>
<input />
</form>WCAG 2.1 - 1.3.1 Info and Relationships
Clickable element that triggers an action
HTML Equivalent: <button>
Required Attributes:
accessible nameKeyboard:
Common Mistakes:
<div role="button" tabindex="0" onclick="handleClick()">
Click Me
</div>WCAG 2.1 - 4.1.2 Name, Role, Value
Hyperlink to another page or location
HTML Equivalent: <a href>
Keyboard:
Common Mistakes:
<span role="link" tabindex="0" onclick="navigate()">
Go to page
</span>WCAG 2.1 - 4.1.2 Name, Role, Value
Tab in a tablist
Required Attributes:
aria-selectedaria-controlsKeyboard:
<button role="tab" aria-selected="true" aria-controls="panel-1">
Tab 1
</button>WCAG 2.1 - 4.1.2 Name, Role, Value
Container for tabs
Common Attributes:
aria-labelaria-labelledbyaria-orientation<div role="tablist" aria-label="Settings Tabs">
<button role="tab">...</button>
</div>WCAG 2.1 - 4.1.2 Name, Role, Value
Content panel for a tab
Required Attributes:
aria-labelledby<div role="tabpanel" aria-labelledby="tab-1" tabindex="0">
Tab content...
</div>WCAG 2.1 - 4.1.2 Name, Role, Value
Checkable input with three states
HTML Equivalent: <input type="checkbox">
Required Attributes:
aria-checkedKeyboard:
<div role="checkbox" aria-checked="false" tabindex="0">
Accept terms
</div>WCAG 2.1 - 4.1.2 Name, Role, Value
Radio button in a radiogroup
HTML Equivalent: <input type="radio">
Required Attributes:
aria-checkedKeyboard:
<div role="radio" aria-checked="false" tabindex="0">
Option 1
</div>WCAG 2.1 - 4.1.2 Name, Role, Value
Range input with min/max values
HTML Equivalent: <input type="range">
Required Attributes:
aria-valuenowaria-valueminaria-valuemaxKeyboard:
<div role="slider" aria-valuenow="50" aria-valuemin="0" aria-valuemax="100" tabindex="0">
</div>WCAG 2.1 - 4.1.2 Name, Role, Value
Input with popup list of options
Required Attributes:
aria-expandedaria-controlsKeyboard:
<input role="combobox" aria-expanded="false" aria-controls="listbox-1" aria-autocomplete="list" />WCAG 2.1 - 4.1.2 Name, Role, Value
Menu with selectable items
Keyboard:
Common Mistakes:
<ul role="menu">
<li role="menuitem">Option 1</li>
<li role="menuitem">Option 2</li>
</ul>WCAG 2.1 - 4.1.2 Name, Role, Value
Self-contained composition
HTML Equivalent: <article>
<div role="article">
<h2>Article Title</h2>
<p>Content...</p>
</div>WCAG 2.1 - 1.3.1 Info and Relationships
Heading for a section
HTML Equivalent: <h1> - <h6>
Required Attributes:
aria-levelCommon Mistakes:
<div role="heading" aria-level="2">Section Heading</div>WCAG 2.1 - 1.3.1 Info and Relationships
List container
HTML Equivalent: <ul>, <ol>
<div role="list">
<div role="listitem">Item 1</div>
<div role="listitem">Item 2</div>
</div>WCAG 2.1 - 1.3.1 Info and Relationships
Item in a list
HTML Equivalent: <li>
<div role="listitem">List item content</div>WCAG 2.1 - 1.3.1 Info and Relationships
Image or image container
HTML Equivalent: <img>
Required Attributes:
accessible name<div role="img" aria-label="Company logo">
<svg>...</svg>
</div>WCAG 2.1 - 1.1.1 Non-text Content
Figure with optional caption
HTML Equivalent: <figure>
<div role="figure" aria-labelledby="caption">
<img src="chart.png" alt="Sales data" />
<div id="caption">Q4 Sales</div>
</div>WCAG 2.1 - 1.3.1 Info and Relationships
Important, time-sensitive message
Common Attributes:
aria-live="assertive" (implicit)Common Mistakes:
<div role="alert">
Error: Form submission failed
</div>WCAG 2.1 - 4.1.3 Status Messages
Advisory information for user
Common Attributes:
aria-live="polite" (implicit)aria-atomic<div role="status" aria-live="polite">
Form saved successfully
</div>WCAG 2.1 - 4.1.3 Status Messages
Live scrolling log of messages
Common Attributes:
aria-live="polite" (implicit)<div role="log" aria-live="polite">
<div>10:30 AM: User logged in</div>
<div>10:31 AM: File uploaded</div>
</div>WCAG 2.1 - 4.1.3 Status Messages
Timer or clock
<div role="timer" aria-live="off">
<span aria-atomic="true">5:00</span>
</div>WCAG 2.1 - 4.1.3 Status Messages
Non-essential scrolling information
Common Attributes:
aria-live="off" (implicit)Common Mistakes:
<div role="marquee" aria-live="off">
Latest news headlines...
</div>WCAG 2.1 - 4.1.3 Status Messages
Dialog window that interrupts main flow
Required Attributes:
aria-label or aria-labelledbyaria-modalKeyboard:
Common Mistakes:
<div role="dialog" aria-labelledby="dialog-title" aria-modal="true">
<h2 id="dialog-title">Confirm Action</h2>
<p>Are you sure?</p>
<button>Confirm</button>
<button>Cancel</button>
</div>WCAG 2.1 - 4.1.2 Name, Role, Value
Modal dialog with important message
Required Attributes:
aria-label or aria-labelledbyaria-describedbyKeyboard:
<div role="alertdialog" aria-labelledby="title" aria-describedby="desc" aria-modal="true">
<h2 id="title">Delete Item?</h2>
<p id="desc">This cannot be undone</p>
<button>Delete</button>
<button>Cancel</button>
</div>WCAG 2.1 - 4.1.2 Name, Role, Value
Help others discover this tool!
