Using ARIA Landmark Roles in WordPress

What’s a girl to write about after so long? Why, things that she loves of course – WordPress and Accessibility. I’ve been getting to know WAI ARIA in recent months, specifically using ARIA landmark roles in WordPress. This seemed like a great place to start as it was a handful of markup to memorize in an otherwise vast amount of ARIA to learn. It’s also familiar to developers if they’ve browsed through WordPress.org themes even if they haven’t realized it yet.

Before we move on, if you’re unfamiliar with what WAI ARIA is ( ARIA for short ), I’ll direct you to W3.org’s reference first.

 

Now if you’re like me, and stopped reading by the second line of that massive intimidating wall of jargon, I’d advise reading something easier on the eyes ( and brain ) like the A11y project’s, “Getting Started with ARIA“. I also found this lengthy article recently, “Introduction to WAI ARIA” written by Gez Lemon, and although it’s from 2008, it cleared up a lot for me. I’d recommend giving it a read through.

Now that we have a basic understanding of what ARIA is ( not the pirate Queen of Omega* ), let’s go over what ARIA landmark roles are and how they can make our WordPress themes more accessible.

* A Mass Effect reference that I couldn’t help, but take advantage of.

What is a Landmark Role?

Before we get into using ARIA landmark roles in WordPress, let’s briefly go over what they are. An ARIA landmark role define regions of a page and serves as a navigational landmark for screen readers. These navigational landmarks help screen readers understand the page’s structure as well as orient screen reader users within that structure. ARIA landmark roles are usually not interactive elements, but wrappers that contain content.

The really nice thing about ARIA landmark roles is that they work nicely with already semantic HTML5 elements. You will see these roles commonly applied to HTML5 elements in existing WordPress.org themes. You can learn more about HTML5 by browsing HTML5 Doctor’s Element Index.

Reviewing Twenty Sixteen

Now that we’ve gone over what ARIA landmark roles are, we’ll be reviewing the Twenty Sixteen theme as a reference to visualize these roles in action. We’ll go over each role’s definition, provide a code sample for what it looks like and provide the file it can be found.

Role: Banner

The banner role is used to mark site oriented content rather than page oriented content. This can be a wrapper that contains a logo, site title, or some other form of site identity. Only one element should be marked with the banner role. Banners are typically located on the top of the page and usually span the full width.

In the Twenty Sixteen theme, this role can be found in the header.php file, on the header HTML5 element.

<header id="masthead" class="site-header" role="banner">

Role: Navigation

The navigation role is used to mark navigational elements used to navigate the site or current page. Usually these navigational elements contains links and this role can be applied more than once. In the Twenty Sixteen theme, it can be found twice in header.php. Once for the site’s primary navigation and again for the social navigation. Both times, the navigation role is applied to the nav HTML5 element.

<?php if ( has_nav_menu( 'primary' ) ) : ?>
	<nav id="site-navigation" class="main-navigation" role="navigation" aria-label="<?php esc_attr_e( 'Primary Menu', 'twentysixteen' ); ?>">
		<?php
		wp_nav_menu( array(
		'theme_location' => 'primary',
		'menu_class' => 'primary-menu',
		) );
		?>
	</nav><!-- .main-navigation -->
<?php endif; ?>

<?php if ( has_nav_menu( 'social' ) ) : ?>
	<nav id="social-navigation" class="social-navigation" role="navigation" aria-label="<?php esc_attr_e( 'Social Links Menu', 'twentysixteen' ); ?>">
		<?php
		wp_nav_menu( array(
		'theme_location' => 'social',
		'menu_class' => 'social-links-menu',
		'depth' => 1,
		'link_before' => '<span class="screen-reader-text">',
		'link_after' => '</span>',
		) );
		?>
	</nav><!-- .social-navigation -->
 <?php endif; ?>

In the Twenty Sixteen example above, the navigation role is being used twice. If a particular role appears more than once on a page, you should provide an ARIA label for that role. Reference the example below for the use of ARIA labels.

<nav role="navigation" aria-label="<?php _e( 'Primary Navigation', 'textdomain' ); ?>">
<nav role="navigation" aria-label="<?php _e( 'Secondary Navigation', 'textdomain' ); ?>">

Role: Main

The main role is applied to the wrapper that contains the main or central content of the site. Only one element should be marked with the main role.

In the Twenty Sixteen theme, this role gets applied to the main HTML5 element within several files (e.g. archive.php, index.php, page.php and so on). Here is the example being used in page.php that wraps the loop from Twenty Sixteen.

<main id="main" class="site-main" role="main">
	<?php
	// Start the loop.
	while ( have_posts() ) : the_post();

		// Include the page content template.
		get_template_part( 'template-parts/content', 'page' );

		// If comments are open or we have at least one comment, load up the comment template.
		if ( comments_open() || get_comments_number() ) {
		 	comments_template();
		}

	// End of the loop.
	endwhile;
	?>

 </main><!-- .site-main -->

Role: Complementary

The complementary role is used to mark supporting content that isn’t the main content, but is still important in it’s own right. This is a good role to apply to sidebars or wrappers containing content like related articles, current weather, stocks to watch, and so on. If there is more than one complementary role being used, ARIA labels can be applied as well.

This role is used in Twenty Sixteen in the sidebar.php file on the aside HTML5 element.

<?php if ( is_active_sidebar( 'sidebar-1' ) ) : ?>
	<aside id="secondary" class="sidebar widget-area" role="complementary">
		<?php dynamic_sidebar( 'sidebar-1' ); ?>
	</aside><!-- .sidebar .widget-area -->
<?php endif; ?>

Role: Contentinfo

The contentinfo role is applied to a wrapper that contains information about the parent document ( the main content ). This content can be foot notes, copyrights, and links to privacy/terms of service statements, and is usually located outside of the main content. Only one element should be marked with the contentinfo role.

In Twenty Sixteen, this role is applied to the footer HTML5 element in footer.php.

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

Role: Search

The search role is applied to the search form of a site. For other generic forms that aren’t being used for searching the site, the form role can be applied instead. The search role can mark more than one element and therefore should use ARIA labels where applicable.

In Twenty Sixteen, the search role is applied on the form element in searchform.php.

<form role="search" method="get" class="search-form" action="<?php echo esc_url( home_url( '/' ) ); ?>">

ARIA Landmark Roles Summarized

We’ve gone over all available ARIA landmark roles with the exception of the application role. We’ve also looked over how the code appears using the Twenty Sixteen theme. In all, these are the roles we’ve reviewed along with their purpose:

• banner: Marks the wrapper containing site identity.
• navigation: Marks the wrapper containing navigational elements.
• main: Marks the main content of the site.
• complementary: Marks supporting content to the main content.
• contentinfo: Marks the wrapper containing information about the main content.
• search: Marks the search form.

These roles should only be used on one element:

• banner
• main
• contentInfo

These roles can be used more than once so long as ARIA labels are also applied:

• navigation
• complementary
• search

If you’d like to see a visual of how these roles would be applied on a non-WordPress site, here’s another awesome resource, WAI ARIA Landmark Roles Cheatsheet.

Combining the handful ARIA landmark roles and HTML5 elements is a great way to increase accessibility in our themes. It also fulfills one of WordPress.org’s theme review requirements to use the accessibility-ready tag. While there’s more ARIA to learn, I hope this post on using ARIA landmark roles in WordPress helps to bring us closer to a more accessible web. Looking forward to learning more ARIA so I can continue to share my WordPress adventures here on RachieVee. Until next time!

PS: Just Kidding!

 

After a helpful reader (Adrian) linked me to an article titled HTML Belts and ARIA Braces, and a chat in the WP Slack’s A11y room, this post was in need of an update.

Although currently the use of landmark roles are a requirement for WordPress themes using the accessibility-ready tag, there are some things to keep in mind.

HTML5 elements combined with landmark roles can create redundancy e.g. the role “main” on the “main” HTML 5 element. Keeping landmark roles however, are useful for IE8/older JAWs or in IE11 where HTML5 elements are either not supported at all or are not accessibly supported. In cases other than those however, it is safe to omit the landmark roles on HTML5 elements where the structure is clear.

Whenever not using an HTML5 element, always make use of the landmark role:

<div class="secondary-navigation" role="navigation" aria-label="secondary-navigation">
<!-- some secondary navigation, role applied on div -->
</div>

Always make use of aria-labels regardless of whether a role is present, to distinguish HTML5 elements being used more than once:

<nav aria-label="primary-navigation">
<!-- primary nav, no landmark role, uses label -->
</nav>

<nav aria-label="secondary-navigation">
<!-- secondary nav, no landmark role, uses label -->
</nav>

If supporting IE or outdated assistive technologies – you can continue with the examples I’ve already listed in this post where I’m using both the HTML5 element and it’s corresponding landmark role. You’ll still see these examples in the wild as I’ve shown from the Twenty Sixteen theme. Approach HTML5 and whether landmarks are necessary on a case by case basis depending on your theme or site. Hope this helps! Lots of kudos for Andrea, Andrew, and Joe for helping to clear that all up for me!