References

Beginner-friendly references for web development, with live, editable examples.

The HTML role attribute

ARIA Accessibility All modern browsers Updated
Quick answer

The HTML role attribute tells assistive technology what an element is — its semantic role, such as button, navigation, dialog or alert. It is the foundation of WAI-ARIA. The first rule of ARIA: if a native HTML element already provides the role, use that element instead.

Overview

The role attribute assigns an explicit semantic role to an element, which determines how assistive technology announces it and which aria-* states and properties are valid on it. Roles fall into groups: landmark roles (page regions like navigation and main), widget roles (interactive controls like button, tab and slider), document structure roles (list, table, heading) and live region roles (alert, status).

Use it only when native HTML cannot express the semantics. A real <button> is always better than <div role="button">, because the native element brings focus, keyboard handling and state for free. When you do add a widget role, you take on responsibility for the keyboard behavior and the required aria-* states that role expects.

Syntax

<div role="button" tabindex="0">Custom button</div>

Values

Value
Landmark — banner, navigation, main, complementary, contentinfo, search, region, form
Widget — button, checkbox, radio, switch, slider, spinbutton, tab, tabpanel, menu, menuitem, dialog, tooltip, progressbar, textbox
Document structure — article, list, listitem, heading, table, row, cell, figure, separator, group
Live region — alert, status, log, timer, marquee

Example

Live example 
<!-- Prefer <button>. Only use role="button" when you cannot. -->
<div role="button" tabindex="0" aria-pressed="false">Toggle</div>

Best practices

  • Use a native element instead of a role whenever one exists — the first rule of ARIA.
  • If you give an element a widget role, also provide keyboard support and the states that role requires (e.g. aria-expanded on a disclosure).
  • Do not change the role of an element that already has correct native semantics.
  • Never use abstract roles (like widget or structure) — they are for the spec, not for authors.

Accessibility

The role attribute is the backbone of ARIA, and it is powerful enough to break accessibility when misused. Overriding a native role (for example role="presentation" on a real button) removes built-in behavior and confuses assistive technology. Add a role only when you cannot use a native element, and when you do, commit to the full contract: the expected keyboard interactions, focus management and required aria-* states for that role.

Frequently asked questions

What is the role attribute in HTML?
It defines an element's semantic role for assistive technology — what the element is, such as a button, tab, dialog or navigation landmark.
When should I use the role attribute?
Only when no native HTML element provides the semantics you need. Prefer <button>, <nav>, <dialog> and friends first.
Is it bad to misuse role?
Yes. An incorrect or unnecessary role can make a page less accessible — "No ARIA is better than bad ARIA." Only add a role you fully support with keyboard behavior and states.
What are landmark roles?
Roles like banner, navigation, main and contentinfo that mark page regions so screen-reader users can jump between them. Native elements (<header>, <nav>, <main>, <footer>) provide these automatically.
aria-valuetext