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
--------