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 |
|---|---|
associationlistContains only associationlistitemkey children and their sibling associationlistitemvalue. |
<dl> |
associationlistitemkeyMust be contained in an associationlist. |
<dt> |
associationlistitemvalueAlways a sibling following an associationlistitemkey. |
<dd> |
blockquoteA section of content that is quoted from another source. |
<blockquote> |
captionVisible 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> |
codeA section representing a fragment of computer code. Prohibited attributes: aria-label and aria-labelledby. |
<code> |
deletionContent that is marked as removed or suggested for removal. Prohibited attributes: aria-label and aria-labelledby. |
<del> |
emphasisUsed to stress or emphasize content, but not to suggest importance. Prohibited attributes: aria-label and aria-labelledby. |
<em> |
figureContainer for a graphical document, images, code snippets, or example text. |
<figure> |
headingA 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 |
imageContainer for a collection of elements that form an image. Synonym for img role. |
<img> |
imgContainer for a collection of elements that form an image. Accessible name is required. See the img role for more information. |
<img> |
insertionContent 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> |
meterA scalar measurement within a known range, or a fractional value. Accessible name required. aria-valuenow required.See meter role for more information. |
<meter> |
paragraphA paragraph of content. Prohibited attributes: aria-label and aria-labelledby. |
<p> |
strongImportant, serious, or urgent content. Prohibited attributes: aria-label and aria-labelledby. |
<strong> |
subscriptOne or more subscripted characters. Only use if absence of role would change the content's meaning. Prohibited attributes: aria-label and aria-labelledby. |
<sub> |
superscriptOne 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> |
timeA 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 |