diff --git a/describing-hierachical-structure-with-aria-level.md b/describing-hierachical-structure-with-aria-level.md new file mode 100644 index 0000000000..21b9a84e2a --- /dev/null +++ b/describing-hierachical-structure-with-aria-level.md @@ -0,0 +1,78 @@ +# Describing Hierarchical Structure with `aria-level` + +When elements have a hierarchical relationship within a structure, such as the headers for sections or data arranged in nested files, `aria-level` is used to communicate the hierarchy between elements to assistive technologies. The value of `aria-level` is numeric, with `1` indicating the top level of the structure. The number increases for each level of subsection of nesting. + +Do not use `aria-level` when the DOM structure already accurately represents the element's relationship, as it does for most nest listed structures. + +The attribute `aria-level` can be used on the following roles: +* `heading` +* `listitem` +* `row` +* `tablist` +* `grid` + +## `heading` Role + +Used together, the attribute `aria-level` and role `heading` will be treated the same by assistive technologies as the native HTML header elements: `h1`, `h2`, `h3`, `h4` and `h5`. Do not use attribute `aria-level` and `heading` when a native HTML element can be used. + +This example uses the `heading` role and `aria-level` attribute to communicate levels of headings for a graph created with an SVG. The headings "Deciduous Trees" and "Evergreen Trees" are both subheadings to "Total Trees per Year". + +``` + +``` + +### Remediation Uses Cases + +Because the attribute `aria-level` and the role `heading` can be used to approximate a native HTML section heading element, legacy code which cannot be converted to using HTML header elements should add these roles and attributes to their website's header elements. + +For example, "Definition of a Room" is a subsection of "Housing Specification": + +``` +