Using ARIA Landmark Roles to Improve WordPress Theme Accessibility

ARIA landmark roles help screen readers understand the purpose of various sections of a web page. Unfortunately, they seem to be largely neglected in the WordPress community. Adding landmark roles to a theme is relatively simple and I can’t think of a good reason not to include them in every project. Here is a simple breakdown of the ARIA landmark roles and how they should be applied when building WordPress themes. We’ll start with an explanation of each role and then take look at the code involved in adding each role to a theme.

ARIA Landmark Roles Explained

Banner – This role should be applied to the element that contains the site title, tagline, logo, etc. The banner role is for site-wide content, not page specific content. It should never appear more than once on a page.

Navigation – The navigation role should be applied to elements containing links for navigating the current document or related documents. Unfortunately, the pages, categories, and custom menu widgets in WordPress core do not use this role (as of WordPress 3.8).

Main – This role should be applied to the main content area (the element containing the WordPress loop). This should also be used only once per page.

Complementary – This role should be applied to the element containing the sidebar. If there are multiple sidebars, each sidebar should have this role.

Contentinfo – This role seems to be vaguely defined as “A large perceivable region that contains information about the parent document.” However, it is typically used on the element containing the footer.

Search – The WordPress search widget uses this role by default, but if additional search functionality is built into a theme, the search role should be used on the containing form element.

There are a couple other landmark roles that don’t usually relate to WordPress themes, but I’ll mention them here anyway.

Application – This role is used when some sort of special software is running in a section of the page and the screen reader should return control of the navigation keys back to the browser. This should be used very sparingly.

Form – This role should be used around a collection of form elements. Since forms are typically left to plugins, I’ll just mention it briefly here. I will not include a form example in the next section.

Examples of ARIA Landmark Roles in Use

All the examples in this tutorial will be taken from the Solum WordPress starter theme. To see the code with more context, take a look at the Solum Github repository.

Banner – The banner role is used in the header.php file on the element that contains the site title and description.

<div id="branding" role="banner">
    <?php echo apply_filters( 'site_name', '<p class="site-title"><a href="' . esc_url( home_url( '/' ) ) . '">' . get_bloginfo('name') . '</a></p>' ); ?>
    <?php echo apply_filters( 'site_description', '<p class="site-description">' . get_bloginfo( 'description' ) . '</p>' ); ?>

Navigation – At the time of this writing, the Solum theme doesn’t have a navigation menu built in, so we’ll use the WordPress admin bar as an example of the ARIA “navigation” role in action.

<div class="quicklinks" id="wp-toolbar" role="navigation" tabindex="0">

Main – The ARIA “main” role is applied to the main content area. In the case of the Solum theme, this is the #content div. A number of different files use this div, so the role must be applied everywhere the div is used. The example below is from the index.php file.

 <div id="content" class="hfeed" role="main">

Complementary – Each sidebar should be assigned the “complementary” ARIA role. This example is from the sidebar.php file.

<div id="secondary" class="sidebar" role="complementary">
    <?php dynamic_sidebar( 'sidebar-1' ); ?>
</div><!-- #sidebar-->

Contentinfo – As mentioned before, the definition for this role is quite vague. Consequently, I’ve followed the lead of Automattic and a number of other theme companies and used this role on the #footer element in the footer.php file.

<div id="footer" class="site-footer" role="contentinfo">

Search – The Solum theme doesn’t include specific search functionality because it is already built into WordPress core. This example is from the default WordPress search widget.

<form role="search" method="get" id="searchform" class="searchform" action="http://localhost/wordpress-parental/">
		<label class="screen-reader-text" for="s">Search for:</label>
		<input type="text" value="" name="s" id="s" />
		<input type="submit" id="searchsubmit" value="Search" />

Now please make sure to add the proper ARIA roles to your next project. Thanks!