Summary

Use ARIA landmarks for significant content components that a user is likely to want quick access to and provide meaningful labels for each.

Techniques

Examples

Example 1 — Landmark role with explicit label

The aria-labelledby attribute is used to ensure that a label is correctly associated with its landmark role, the (the value of the attribute is the ID of the element containing the label, in this example the h2 element).

<section role="doc-endnotes" aria-labelledby="note_hd">
    <h2 id="note_hd">End Notes</h2>
    …
</section>
Example 2 — Landmark role with ambiguous label

If a landmark section contains content before its heading, the aria-labelledby should always be used to ensure the heading is correctly identified as the label.

<section role="chapter" aria-labelledby="c23_hd">
	<img src="img/comic/panel23.jpg" alt="Cartoon panel before chapter start"/>
	<details>
		<summary>Description</summary>
		<p>…</p>
	</details>
    <h2 id="c23_hd">Chapter 23</h2>
    …
</section>
Example 3 — Landmark role without a label

If there is only one instance of a landmark role in a document, an explicit label is not required. Assistive technologies will only announce the generic type of landmark (e.g., that a doc-index is an "index"), but users will hear the heading after navigating to it.

<section role="doc-chapter">
    <h2>Chapter 1</h2>
    …
</section>
Example 4 — Landmark with added label

The following landmark does not have an explicit title, so a label is provided using the aria-label attribute.

<section role="chapter" aria-label="Chapter 21">
    <p>I awoke to find …</p>
    …
</section>
Example 6 — Landmark without a unique label

The following landmark does not have a unique label (i.e., there is more than one of the same landmark in the document with the same title). To differentiate the landmark, a sequential number is provided for AT using the hidden attribute. Because this element is hidden, it also needs to be referenced from the aria-labelledby attribute (i.e., hidden descendant content is ignored, so an explicit reference is needed to capture the number). Ideally, each landmark would be given a visible sequence number for the benefit of all users.

<aside aria-labelledby="pp2 pp2-num">
    <h4 id="pp2">Practice Problem <span id="pp2-num" hidden="">2</span></h4>
    …
</section>

Explanation

ARIA landmarks are used with web sites to allow users to identify and quickly move between the different primary regions of a page: site headers and footers, search boxes, advertisements, and the main content area.

The landmarks found on a page are compiled by AT into a list of links. Users are expected to be able to quickly scroll through the landmarks in order to orient themselves to the page and access the specific section of content they are looking for.

While publications are typically structured such that each document only contains the text of a single section or chapter, landmarks still play an important role in allowing users access to key components within one of these major regions (e.g., to quickly access notes, a glossary, learning objectives, practice problems, sidebars, or interactive widgets).

Not every section of content in a publication needs to be a landmark, or should be. Landmarks should be reserved only for key sections that the user might need to access quickly. A user is more likely to appreciate being able to reach a glossary, for example, than have a listing of every section and subsection.

The DPUB-ARIA module contains the following landmark roles for publications:


The following navigation roles are also landmarks:


In addition, the following roles in the core ARIA specification are landmarks:


Frequently Asked Questions

Does every chapter/section need to be a landmark?

No.

Landmarks should not be used as an alternative table of contents as they do no preserve the heading structure of the document. Try to limit the use of landmarks to the components within the page that a user would otherwise have to manually search for. Creating too many landmarks forces users to hunt through a long list.

If the user wants to move by section heading or peruse the table of contents, options are already available to do so. Only identify the major section(s) of content within a document, if necessary (i.e., the chapters or top-level sections, not every subsection).

Is every section with a heading a landmark?

No.

A section tag is only a landmark when one or both of the following are true:

  • It has a role attribute attached to it that specifies a landmark role.
  • It has an aria-label, aria-labelledby or title attribute attached to it.

In all other cases, a section has no specific semantic attached to it (i.e., it is similar in nature to a div).

Does every landmark require a label?

No.

But, the safest option is to always provide a label using one of the aria-labelledby, aria-label or title attributes.

Technically, you only have to use these attributes when more than one of the same landmark role is present on the page (e.g., two or more doc-chapter or doc-bibliography). In these cases, the lack of a unique label can make it more difficult for users to find the one they are looking for. For example, if there are two indexes, without unique labels a user would not be able to determine which is the topical index and which the index of names without manually checking each.

In workflows that combine data from different sources, or chunk content differently depending on the out, it is best practice to make the labels explicit. Doing so will avoid unintended violations of WCAG requirements.

Should I use the title or aria-label attribute for hidden labels?

If a label is not available in the text, preference should always be given to the aria-label attribute. It has higher precedence in the calculation of accessible names for elements and controls and title has a history of poor support.

Why should landmark names be unique?

When there is more than one of the same landmark role in a document, providing unique names avoids confusion about which particular one is being accessed. Ideally, the title of each component will make clear its purpose, but if the same name is reused for each (e.g., multiple "practice problem" sidebars), a unique identifier would improve the usability. The identifier should be something helpful, such as the subsection the component belongs to or the page it is found on in a print addition.

What is the difference between ARIA landmarks and EPUB's landmarks/guide?

ARIA landmarks are compiled for individual web pages, so they do not persist from one document to the next. As EPUB publications consist of many documents, reading systems need an effective way to locate key content across the entire publication. EPUB's landmarks (EPUB 3) and guide (EPUB 2) were designed to solve this problem of landmarks spread across many documents.

For maximum interoperability, it is recommended to provide both types of landmarks.

Why can't I use the landmark role?

The landmark role is what the WAI-ARIA specification refers to as an abstract role. It is not meant to be implemented directly, but used as the top-level definition from which the roles you can use inherit.

For landmarks without a specific role, the region role can be used with an meaningful label.

Why does aside require a label but not section?

Despite the best intentions when it was introduced, the section element has been used the same way as div (i.e., for purely stylistic reasons). As a result, the element does not have a default role to avoid this misuse disadvantaging users of assistive technologies.

As a result, the following example is not a landmark, even though there is a heading:

<section>
    <h2>Section 3.1.1 — Elephants on Parade</h2>
    …
</section>

If you assign a label to the element, however, it assumes the role of region and becomes a landmark:

<section aria-labelledby="s311">
    <h2 id="s311">Section 3.1.1 — Elephants on Parade</h2>
    …
</section>

Conversely, the aside element has the implicit role of complementary so requires a label. For more information about the implicit roles of HTML elements, refer to the ARIA in HTML document.

Why can't I use landmarks on element X?

Some HTML elements are restricted in what roles they accept to prevent overriding necessary semantics.

In particular, the body element has the special role document which cannot be overridden by any other role.

Complete information about what roles are allowed on what elements is provided in the ARIA in HTML document.

Related Links