Last updated 26 June 2014.


WAI-ARIA 1.0 is a set of roles, states, and properties, which can be applied to markup to provide rich semantics, increasing accessibility and interoperability. Although WAI-ARIA properties were not valid in xhtml 1.0, they are valid in HTML5, and can therefore be applied in the markup of Drupal 8. By using the role attribute with an HTML element, authors can provide more information about the purpose of components on the page.


An example of applying a role to an HTML element would be <div role="main"> ... </div>, which would be used to indicate the main content of the page.

Each role falls into one of the following categories: abstract, widget, document structure, and landmark. Abstract roles are not used by web authors, widget roles are used for user interface components, document structure roles are used to organize the structure of the page, and landmark roles are used for regions of the page that are navigational landmarks.

Landmark Roles

The following table is a listing of landmark roles and their descriptions. For a thorough listing of WAI-ARIA roles see The Roles Model

Landmark Role Role Description
application A region declared as a web application, as opposed to a web document
banner A region that contains mostly site-oriented content, rather than page-specific content. Site-oriented content typically includes things such as the logo or identity of the site sponsor, and site-specific search tool. A banner usually appears at the top of the page and typically spans the full width
complementary A supporting section of the document, designed to be complementary to the main content at a similar level in the DOM hierarchy, but remains meaningful when separated from the main content.
There are various types of content that would appropriately have this role. For example, in the case of a portal, this may include but not be limited to show times, current weather, related articles, or stocks to watch. The complementary role indicates that contained content is relevant to the main content. If the complementary content is completely separable main content, it may be appropriate to use a more general role.
contentinfo A large perceivable region that contains information about the parent document.
Examples of information included in this region of the page are copyrights and links to privacy statements.
Within any document or application, the author SHOULD mark no more than one element with the contentinfo role.
form A landmark region that contains a collection of items and objects that, as a whole, combine to create a form.
main The main content of a document.
This marks the content that is directly related to or expands upon the central topic of the document.
Within any document or application, the author SHOULD mark no more than one element with the main role.
navigation A collection of navigational elements (usually links) for navigating the document or related documents.
search A landmark region that contains a collection of items and objects that, as a whole, combine to create a search facility.

WAI-ARIA and HTML5 Compatibility

There is some overlap between HTML5 semantic elements and WAI-ARIA semantics. For a detailed listing of how to use WAI-ARIA roles, states, and properties, with HTML5 see 3.2.7 WAI-ARIA — HTML5 (Edition for Web Authors)

Applying Roles in Drupal

When roles can be applied in preprocess functions it is preferable to do so, even if it is necessary to create a new preprocess function.

The following example shows a newly created preprocess function, in search.module, to add the 'search' role to the search block.

function search_preprocess_block(&$variables) {
  if ($variables['block']->module == 'search') {
    $variables['attributes_array']['role'] = 'search';

In the above example only the module name was used as a condition for the if statement, as there is only one block generated by this module. If the module generated multiple blocks, which required different roles, then it would be necessary to add a condition for the block delta as well.

By adding the role attribute to the existing attributes array it is possible to have all attributes for the block rendered simultaneously.