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> |
listA section containing listitem elements.See list role for more information |
<ol><ul> |
listitemA single item in a list or directory.Must be contained in a list (like <li>).See listitem role for more information. |
<li> |
markMarked 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> |
termWord 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 |