HTML role Attribute

HTML role Attribute

The HTML role attribute assigns an ARIA role to an element, helping assistive technologies understand the element's purpose and how users are expected to interact with it. Native HTML elements already provide built-in semantics, so an explicit role should only be added when it is appropriate and permitted.

Elements That Use the role Attribute

The role attribute can be specified on HTML elements where the chosen ARIA role is permitted. Many HTML elements already have an implicit ARIA role, and ARIA in HTML defines restrictions on which explicit roles may be used with individual elements.

role Value

The value of the role attribute is one or more space-separated ARIA role names. When more than one role is supplied, the roles are evaluated in order and the first role that the browser recognizes and supports is used.

<div role="navigation">
  ...
</div>

Role names describe the semantic purpose of an element rather than its visual appearance.

Implicit and Explicit Roles

Many HTML elements have an implicit ARIA role because their native semantics already communicate their purpose to browsers and assistive technologies.

<button type="button">Save Changes</button>

A <button> element already has button semantics, so adding role="button" normally provides no additional benefit.

An explicit role can be useful when an element needs permitted ARIA semantics that differ from or supplement its native HTML semantics.

<div role="status">
  Your changes have been saved.
</div>

In this example, the status role identifies the element as a status message for assistive technologies.

Common ARIA Roles

ARIA defines many roles for landmarks, document structures, widgets, live regions, and other interface components.

Each ARIA role has its own requirements and supported states and properties. A role should only be used when its meaning and required behavior match the element.

Use Native HTML When Possible

Use a native HTML element when one already provides the required semantics and behavior. Native elements generally provide built-in keyboard interaction, focus behavior, form behavior, and accessibility semantics that would otherwise need to be recreated.

For example, use a real <button> element instead of giving a generic <div> the button role.

<button type="button">Open Menu</button>

This is generally preferable to:

<div role="button">Open Menu</div>

role Does Not Add Behavior

Adding a role changes the accessibility semantics exposed by an element, but it does not automatically add the behavior normally associated with that role.

<div role="button">Open Menu</div>

The button role does not automatically make the <div> keyboard accessible, focusable, or behave like a native <button>. When a custom widget is necessary, the author must provide the required keyboard interaction, focus management, states, and behavior.

Accessibility

The role attribute affects how an element is represented to assistive technologies, so incorrect roles can make a page more difficult to understand or operate.

Do not add ARIA roles simply to change how an element is announced. Choose semantic HTML first, and add an explicit role only when the role is valid for the element and accurately describes its purpose.

Some HTML elements restrict or prohibit explicit roles because changing their native semantics would conflict with the meaning defined by HTML. Always follow the ARIA in HTML requirements for the element and role being used.

Common Mistakes

Do not add a redundant role when the native HTML element already provides the required semantics. For example, <button role="button"> is normally unnecessary.

Do not assume that adding a role gives an element the behavior of the corresponding native control. role="button" does not by itself add keyboard support or button behavior to a <div>.

Do not use a role that conflicts with the permitted semantics of an HTML element. ARIA in HTML defines which roles are allowed or prohibited for individual elements.

Do not choose a role based only on visual appearance. The role should describe the semantic purpose of the element.

Browser Support

Baseline: Widely available indicates a feature has been supported by core browsers for at least 30 months. At this stage, the feature is considered stable and safe for most websites to use without needing to worry about compatibility issues or fallbacks, as it is supported by the vast majority of users' devices and browser versions.

The role attribute and ARIA roles are supported by current core browsers and accessibility APIs, although support for individual roles can vary by browser, operating system, and assistive technology.

Checking Browser Support

For current browser compatibility information, visit Can I Use? . Search for the HTML element or attribute you want to check. You can also narrow your search by entering an element name and attribute name separated by a colon. Search results can include related HTML features, element attributes, input types, APIs, and other technologies, so select the result that most closely matches the feature you are checking.

Try the role Attribute

The example uses role="status" to identify a message as status information for assistive technologies.

Summary

The HTML role attribute assigns ARIA semantics to an element so browsers and assistive technologies can understand its purpose. Native HTML semantics should be used whenever possible, and explicit roles should only be added when they are valid for the element and accurately describe its function. Adding a role changes accessibility semantics but does not automatically add the behavior associated with that role.