ARIA: document structural roles

ARIA document-structure roles are used to provide a structural description for a section of content.

Structural ARIA roles were originally created as a bridge to inform assistive technologies of HTML5 elements that were not yet fully supported in browsers. Some roles, like presentation, toolbar and tooltip, provide information on the document structure to assistive technologies in cases where equivalent native HTML elements don't exist. Other roles, including those listed in the table below, are not needed, as there are semantic HTML elements with the same meanings. In many cases, these equivalent HTML elements have always been supported.

Note: These structural roles all have semantic HTML equivalents. They are included here for completeness of documentation. Preferably, they should not be used by web authors.

Some structural roles, like suggestion, don't have HTML equivalents, and therefore have separate documentation. Some structural roles with HTML equivalents, like heading, have ARIA-attribute requirements. They are listed below with links to their individual role documentation.

Most of the following roles were never needed but were added to ARIA for completeness. We've included them here for completeness as well.

Structural roles with HTML equivalents

The structure roles with HTML equivalents are listed below:

ARIA role & description HTML Equivalent
associationlist
Contains only associationlistitemkey children and their sibling associationlistitemvalue.
<dl>
associationlistitemkey
Must be contained in an associationlist.
<dt>
associationlistitemvalue
Always a sibling following an associationlistitemkey.
<dd>
blockquote
A section of content that is quoted from another source.
<blockquote>
caption
Visible content that names, and may also describe, a figure, table, grid, or treegrid.
Only found in those 4 roles. A caption's id is generally referenced by a figure, grid, table, or treegrid's aria-labelledby attribute.
Prohibited attributes: aria-label and aria-labelledby.
<caption>
<figcaption>
code
A section representing a fragment of computer code.
Prohibited attributes: aria-label and aria-labelledby.
<code>
deletion
Content that is marked as removed or suggested for removal.
Prohibited attributes: aria-label and aria-labelledby.
<del>
emphasis
Used to stress or emphasize content, but not to suggest importance.
Prohibited attributes: aria-label and aria-labelledby.
<em>
figure
Container for a graphical document, images, code snippets, or example text.
<figure>
heading
A heading for a section of the page.
The aria-level attribute is required to indicate the nesting level.
See the heading role for more information.
h1, h2, h3, h4, h5, and h6
image
Container for a collection of elements that form an image. Synonym for img role.
<img>
img
Container for a collection of elements that form an image.
Accessible name is required.
See the img role for more information.
<img>
insertion
Content that is marked as added or content that is being suggested for addition.
Prohibited attributes: aria-label and aria-labelledby.
<ins>
list
A section containing listitem elements.
See list role for more information
<ol>
<ul>
listitem
A single item in a list or directory.
Must be contained in a list (like <li>).
See listitem role for more information.
<li>
mark
Marked or highlighted for reference or notation purposes.
See mark role for more information.
<mark>
meter
A scalar measurement within a known range, or a fractional value.
Accessible name required. aria-valuenow required.
See meter role for more information.
<meter>
paragraph
A paragraph of content.
Prohibited attributes: aria-label and aria-labelledby.
<p>
strong
Important, serious, or urgent content.
Prohibited attributes: aria-label and aria-labelledby.
<strong>
subscript
One or more subscripted characters.
Only use if absence of role would change the content's meaning.
Prohibited attributes: aria-label and aria-labelledby.
<sub>
superscript
One or more superscripted characters.
Only use if absence of role would change the content's meaning.
Prohibited attributes: aria-label and aria-labelledby.
<sup>
term
Word or phrase with an optional corresponding definition.
Prohibited attributes: aria-label and aria-labelledby.
See term role for more information.
<dfn>
time
A valid date or time string format list a specific point in time.
Prohibited attributes: aria-label and aria-labelledby.
<time>

Note: The aria-label and aria-labelledby attributes are prohibited on code, caption, deletion, emphasis, generic, insertion, mark, paragraph, presentation, none, strong, subscript, superscript, suggestion, term, and time, and should only be used on interactive content.

Best Practices

Do not use structural roles. Opt for HTML semantic elements instead.

Specifications

Specification
Accessible Rich Internet Applications (WAI-ARIA)
# document_structure_roles

See Also