This Wiki page is edited by participants of the WCAG Working Group. It does not necessarily represent consensus and it may have incorrect information or information that is not supported by other Working Group participants, WAI, or W3C. It may also have some very useful information.
Using ARIA landmarks to identify regions of a page
From WCAG WG
- Surveyed by TF March 19, 2012
- 1 Nov 2012: Ready for Review
- WG survey 14 Jan 2013, returned to TF
- Techniques Task Force: ARIA techniques for 29 Aug 2013
Sufficient vs Advisory for 2.4.1? The arguments are very similar to those for using headings for 2.4.1. For non-AT users, there is no native browser support, although there is at least 1 plugin.
User Agent Notes [To be published separately]
- Jaws V.11 and greater has complete support.
- ChromeVox V.1 and greater has complete support
- VoiceOver V.3 and greater supports all landmarks except “form”.
- NVDA 2 supports all landmarks except it will not support navigation to “application”
- Window Eyes as of V.7 does not support ARIA landmarks.
This technique relates to:
The purpose of this technique is to provide programmatic access to sections of a web page. Landmark roles (or "landmarks") break the page into easy to navigate sections. Landmarks help assistive technology (AT) users orient themselves to a page and help them navigate easily to various sections of a page.
It is also an easy way to skip over blocks of content that are repeated on multiple pages and provide programmatic structure to a page. For instance, if there is a common navigation menu found on every page, landmark roles (or "landmarks") can be used to skip from section to section, and to save assistive technology users and keyboard users the trouble and time of tabbing through a large amount of content to find what they are really after, much like a traditional "skip links" mechanism. A blind user who may be familiar with a news site's menu, and is only interested in getting to the top story could easily navigate to the "main" landmark, and bypass dozens of menu links. In another circumstance, a user who is blind may want to quickly find a navigation menu, and can do so by jumping to the navigation landmark.
Landmarks also can help sighted keyboard-only users navigate to sections of a page using a browser plugin.
Landmarks are inserted into the page using the role attribute on an element that marks the section. The value of the attribute is the name of the landmark. These role values are listed below:
- banner: A region that contains the prime heading or internal title of a page.
- complementary: Any section of the document that supports the main content, yet is separate and meaningful on its own.
- contentinfo: A region that contains information about the parent document such as copyrights and links to privacy statements.
- form: A region of the document that represents a collection of form-associated elements, some of which can represent editable values that can be submitted to a server for processing.
- main: Main content in a document. Generally, a page will have only one role="main".
- navigation: A collection of links suitable for use when navigating the document or related documents.
- search: The search tool of a Web document.
- application: A region declared as a web application, as opposed to a web document. (note: The role of application should only be used with caution because it gives a signal to screen reading software to turn off normal web navigation controls. Simple widgets should generally not be given the application role, nor should an entire web page be given the application role, unless it is not to be used at all like a web page, and not without much user testing with assistive technology.)
ARIA also defines the following role which is not a landmark and may not be included in AT lists of landmark regions.
- region: A generic area of a page that may not be covered by other types of landmarks. It can be used in conjunction with aria-label or aria-labelledby to provide a custom label for that section of the page. The role of region should be used prudently, because if overused they can make the page overly verbose for screen reader users.
There are cases when a particular landmark role could be used more than once on a page, such as on primary and secondary navigation menus. In these cases, identical roles should be disambiguated from each other using a valid technique for labelling regions (see examples below).
Landmarks should supplement native semantic markup such as HTML headings, lists and other structural markup. Landmarks are interpretable by WAI-ARIA-aware assistive technologies and are not exposed by browsers directly to users.
The following example shows how landmarks might be added to an HTML4 or XHTML 1.0 document:
<div id="header" role="banner">A banner image and introductory title</div> <div id="sitelookup" role="search">....</div> <div id="nav" role="navigation">...a list of links here ... </div> <div id="content" role="main"> ... Ottawa is the capital of Canada ...</div> <div id="rightsideadvert" role="complementary">....an advertisement here...</div> <div id="footer" role="contentinfo">(c)The Freedom Company, 123 Freedom Way, Helpville, USA</div>
The following example shows a best practice of how landmarks might be added to an HTML4 or XHTML 1.0 document in situations where there are more than two of the same type of landmark on the same page. For instance, if a navigation role is used multiple times on a Web page, each instance may have a unique label specified using aria-labelledby:
<div id="leftnav" role="navigaton" aria-labelledby="leftnavheading"> <h2 id="leftnavheading">Institutional Links</h2> <ul><li>...a list of links here ...</li> </ul></div> <div id="rightnav" role="navigation" aria-labelledby="rightnavheading"> <h2 id="rightnavheading">Related topics</h2> <ul><li>...a list of links here ...</li></ul></div>
The following example shows a best practice of how landmarks might be added to an HTML4 or XHTML 1.0 document in situations where there are more than two of the same type of landmark on the same page, and there is no existing text on the page that can be referenced as the label.
<div id="leftnav" role="navigaton" aria-label="Main Navigation"> <ul><li>...a list of links here ...</li></ul> </div> <div id="rightnav" role="navigation" aria-label="Secondary Navigation"> <ul><li>...a list of links here ...</li> </ul></div>
The following example shows a best practice of how a generic "region" landmark might be added to a weather portlet. There is no existing text on the page that can be referenced as the label, so it is labelled with aria-label.
<div role="region" aria-label="weather portlet"> ... </div>
The following example shows a best practice of how a generic "region" landmark might be added to a stock ticker portlet. There is existing text on the page that can be referenced using aria-labelledby.
<div role="region" aria-labelledby="t1"> <h2 id="t1">Stock Ticker Portlet</h2> ... </div>
The following example shows a search form with a "search" landmark. The search role typically goes on the form field or a div.
<form role="search"> <label for="56">search</label><input id="56" type="text" size="20"> ... </form>
- WAI ARIA 1.0 Authoring Practices
- Enabling landmark-based keyboard navigation in Firefox
- Not All ARIA Widgets Deserve role="application"
- When Should You Use ARIA Role="Application"?
- H69: Providing heading elements at the beginning of each section of content (HTML)
- SCR28: Using an expandable and collapsible menu to bypass block of content (Scripting)
- Examine each element with a landmark role.
- Examine whether the landmark role attribute is applied to the section of the page that corresponds with that role. (i.e., the "navigation" role is applied to a navigation section, the "main" role is applied to where the main content begins.)
Tests #1 and #2 are true.