Custom ARIA Landmark Roles

The Custom Roles feature in Web Accessibility Toolkit lets you assign ARIA landmark roles (like main, banner, navigation, or search) to specific elements using CSS selectors. This is particularly useful when your theme uses generic elements such as <div> or <section> without any semantic meaning.

By applying appropriate roles, you can define the structure of your page for assistive technologies, making your content more navigable and accessible to screen reader users.

What accessibility issue does this fix

This option addresses a common gap in many themes: the absence of proper ARIA roles or semantic HTML tags. Assigning roles to major content areas helps screen readers understand and navigate the layout more effectively.

It supports compliance with:

• 1.3.1 – Info and Relationships (opens in new tab)
• 2.4.1 – Bypass Blocks (opens in new tab)
• 4.1.2 – Name, Role, Value (opens in new tab)

These success criteria focus on helping users locate repeated content (like headers or navigation), understand relationships between page elements, and access important sections directly.

How does Custom Roles affect accessibility

Without proper roles or semantic tags, assistive tech users have to read through your site sequentially. This is frustrating and time-consuming, especially on content-heavy pages.

By adding ARIA landmark roles:

• Users can jump directly to important areas (e.g., navigation, search, main content, sidebars)
• You provide clear meaning to regions that might otherwise be visually distinct but inaccessible in structure
• Multiple navigation or complementary regions can be distinguished using aria-label or aria-labelledby if needed

Important: Do not use a landmark role on a semantic element that already has that role natively (e.g., <main>, <nav>, <header>, <aside>, etc.). Doing so redundantly can confuse screen readers.

How to add Custom Roles using Web Accessibility Toolkit

1. Go to Settings > Web Accessibility.
2. Open the Roles tab.
3. Scroll to the Custom Roles section.
4. Click Add Row to create a new rule.
5. In the Selector field, enter the CSS selector targeting the element (e.g. .sidebar, #main-content, or div.footer-wrapper).
6. In the Role dropdown, select the appropriate role for the element’s function:
   • main – for primary content
   • banner – for site headers
   • navigation – for menus or links
   • complementary – for sidebars
   • contentinfo – for footers
   • search, form, region, etc.
7. Click Save Changes.

If you’re unsure what each role means, view the official WAI-ARIA Landmark Roles Guide (opens in new tab).

How to confirm that Custom Roles is working

1. Visit the page where your targeted element appears.
2. Right-click and Inspect the element using your browser’s Developer Tools.
3. Check if the correct role="..." attribute has been applied to the element.
4. You can also run your site through an accessibility checker like:
   • axe DevTools (opens in new tab)
   • Wave (opens in new tab)
   • Or test using screen reader software to hear how it navigates between landmarks.

If you don’t see the role applied, double-check your CSS selector for accuracy.