ARIA Essentials

This page lists the essential ARIA roles, states & properties that every developer should be familiar with, including a brief overview on their usage.

aria-label & aria-labelledby

Label an element using one of these properties.

Use aria-labelledby if there is visible text onscreen that can be used to label the element (a nearby heading, for example).

Use aria-label when there is no suitable labeling text onscreen (this issue is common with icon buttons, for example).

These attributes are not recommended if the element already has a natural label such as inner-text or an associated label tag, as the ARIA attribute may take precedence, therefore overriding the natural label.


Describe an interactive element using existing onscreen text.

A description is different from a label. Labels are typically short and to the point, whereas descriptions are longer and more verbose.

For example, using this attribute we could describe the inline error message of a form field, or the title of the item belonging to an 'Add to Cart' button.


Informs the user that this element can be clicked or pressed to trigger an action.

Commonly used to convert a plain DIV or SPAN into an interactive button. Also useful in converting hijaxed hyperlinks into buttons.

Of course, supplying this role alone is not sufficient to convert a DIV or SPAN into a fully functioning, keyboard-accessible button. That behaviour must be added with JavaScript. Better yet, just try and use a native button element which will give you the screen reader role and keyboard behaviour for free.


Indicate whether the element, or another element it controls, is currently expanded or collapsed.

Often used on 'expando' or 'show more' buttons that dynamically hide & show content. Also used on buttons and comboboxes that control menu and auto-complete overlays respectively.


Announce any content or visibility changes inside an element that may be outside the user's area of focus.

Changes can be notified assertively, interrupting the screenreaders current announcement, or politely after the current announcement has finished.

By default, only the updated content inside the element will be announced, rather than the entire content of the element. This behaviour can be changed with the aria-atomic property.

It is good practice to try and use live-regions to announce what content has changed, rather than the actual content itself.

role=dialog & role=alertdialog

Dialog informs the user that they are inside of a modal window. A modal window typically prompts the user to enter some information, confirm a response or to browse new content.

Alertdialog effectively converts the entire dialog into an assertive live-region. This behaviour may be desirable in cases where the window contains updating content, error messages or workflows.

Every modal window requires a role of dialog or alertdialog.

WARNING! Our final set of ARIA attributes listed below are deemed dangerous and therefore essential knowledge in order to avoid their misuse!


Used on a button or menuitem that triggers a menu (or submenu) overlay.

The term 'menu' is important here because this property is to be used in conjunction with the menu and menubar roles only.

The JAWS screenreader will announce 'has menu', so you can see that despite the name of this attribute, it is not intended to be used on elements that open other kinds of popup overlay - such as modals, tooltips, flyouts, etc.


Removes an element for screenreader users only.

Caution must be exercised when applying this attribute because it is rare that we want to give screenreader users a different experience, or different content, to other users.

This attribute may only be used if intended to improve the experience for users of assistive technologies by removing redundant or extraneous content.

Note that setting aria-hidden to true is not necessary if the element already has CSS 'display: none' or the HTML5 hidden attribute.


Remove the default semantic meaning of an element.

You can think of this role as essentially converting an element into a meaningless DIV (block) or a SPAN (inline) but retaining it's default styling.

For example, when applied to a table, the screenreader would no longer announce it as a table or it's children as rows or columns, but it would still appear visually as a table. This behaviour can be desirable for pages or modules that use tables for layout rather than CSS.

Again, this is another attribute that must be used with extreme care.


The majority of web pages, and web developers, will never need to use this role.

By applying this role to an element, you are basically saying that you, as the developer, will now handle all keypresses inside that element rather than the screenreader. So when a screen reader user presses their arrow keys in an attempt to move their virtual cursor, nothing will happen, because you are now handling the behaviour of those keys inside this element.

Applying this role to an element can have severe consequences to screenreader users. Applying this role to the body tag for example, can render the entire page unusable.

Even if you think you need this role, you most probably don't, so please exercise extreme caution. You have been warned!

At the current time of writing the patterns that need role="application" are:

results matching ""

    No results matching ""