Patterns for WAI-ARIA landmark roles in existing HTML

This is a short summary of some methods to add WAI-ARIA landmark roles to existing web pages, e.g. an existing template package for a content management system.

Currently many developers seem to be reluctant to add the role attribute in their markup since it will make pages invalid when using the W3C markup validation service. This is understandable given the attitude developers of content management systems have had to put up with from some people in the industry.

If you want to now more about WAI-ARIA, please have a look at the WAI-ARIA best practices document.

1. Adding the role attribute to relevant elements in markup

This is the easiest way of describing the different parts of your web page, but has the drawback of making the pages invalid. To add the role “main” to a div just add the role attribute with the value “main”:

<div role="main">...</div>

2. Set role attribute values on elements by ID

If your markup already has elements with proper ID attributes that match the landmark regions in scope you can use a simple javascript to set the role attributes when the page has loaded. This will allow your precious template code to pass the markup validation test as well if you or your users worry about that. Consider the following markup fragment:

<div class="special" id="mymaincontent">
<h1>The main content heading</h1>
<p>Some text</p>

Adding landmarks via the role attribute can be done with a simple javascript like this:

function setRoleAttribute(id, rolevalue) {
if(document.getElementById(id)) {
document.getElementById(id).setAttribute("role", rolevalue);
function setAriaRoleElementsById() {
//Add all Id:s and aria roles here
setRoleAttribute("mymaincontent", "main");
window.onload=function(){ setAriaRoleElementsById(); }

For a larger example see Landmarks by ID (view source to see details).

3. Set role attribute values on elements via CSS decoration

If you for some reason are more comfortable using CSS classes instead you can create an unobtrusive javascript like this:

function setAriaRoleElements() {
var els = document.getElementsByTagName('*');
var pattern = new RegExp("ariarole-([\\w]+)", "g");
for ( i=0; i < els.length; i++ ) {
var match = pattern.exec(els[i].className);
if (match && match.length > 1) {
els[i].setAttribute("role", match[1]);
window.onload=function(){ setAriaRoleElements(); }

This will allow you to add CSS classes to existing elements in the following form <div class=”ariarole-main”> and get a role attribute with the value “main” on the same element. This pattern won’t affect validation. For a larger example see Landmarks by CSS decoration.

4. Set role attribute values on arbitrary elements using a javascript library

If you already are using a javascript library like jQuery and Prototype you may be more comfortable using that to set the role attribute. This pattern won’t affect validation. For jQuery a typical example may look like this:

$(document).ready(function() {

You can of course use other selector patterns as well.

If you find errors or have suggestions for improvement, please add a comment below. All code examples are free to use without attribution (yes, I am looking at you WTFPL license).

Comments are closed.