Block ARIA Landmark Roles
Adds ARIA landmark roles and labels to Drupal blocks for improved accessibility and assistive technology support.
block_aria_landmark_roles
Install
composer require 'drupal/block_aria_landmark_roles:^3.0'
composer require 'drupal/block_aria_landmark_roles:^2.0'
composer require 'drupal/block_aria_landmark_roles:8.x-1.4'
Overview
Block ARIA Landmark Roles extends the Drupal block configuration forms to allow site builders to assign WAI-ARIA landmark roles and labels to any block. This module is inspired by the Block Class module and provides a simple yet powerful way to improve website accessibility.
ARIA (Accessible Rich Internet Applications) landmark roles help assistive technologies like screen readers identify and navigate to commonly found sections of web page content. By adding landmark roles such as 'navigation', 'main', 'banner', or 'search' to blocks, users with disabilities can more easily understand the structure of a page and quickly jump to relevant sections.
The module adds a collapsible settings section to each block's configuration form where administrators can select a landmark role from a predefined list and optionally add a custom ARIA label for additional context.
Features
- Adds a 'Landmark role' dropdown to block configuration forms allowing selection from 8 ARIA landmark roles: application, banner, complementary, contentinfo, form, main, navigation, and search
- Adds a 'Label' text field to block configuration forms for custom ARIA labels (aria-label attribute)
- Automatically adds the selected role attribute to block wrapper elements during rendering
- Automatically adds the aria-label attribute when a label is configured
- Uses Drupal's third-party settings system for clean integration with block entities
- Configuration is stored per-block, allowing different roles for different block instances
Use Cases
Marking the main navigation block
Assign the 'navigation' role to your site's primary navigation block. This allows screen reader users to quickly jump to the navigation section using their assistive technology's landmark navigation feature.
Identifying the main content area
Apply the 'main' role to the block containing your main page content. WCAG guidelines recommend having exactly one main landmark per page to help users skip directly to the primary content.
Distinguishing multiple navigation blocks
When a page has multiple navigation blocks (main menu, footer menu, sidebar menu), assign the 'navigation' role to each and use distinct ARIA labels like 'Main navigation', 'Footer navigation', and 'Sidebar navigation' to help screen reader users differentiate between them.
Marking search functionality
Apply the 'search' role to blocks containing search forms. This helps users quickly locate the search functionality on your site.
Identifying header and footer regions
Use the 'banner' role for header blocks (typically containing the site logo and primary navigation) and 'contentinfo' role for footer blocks (typically containing copyright, legal links, and contact information).
Marking sidebar content
Apply the 'complementary' role to sidebar blocks that contain supporting content related to the main content. This is typically used for related articles, additional resources, or supplementary information.
Identifying form blocks
Apply the 'form' role to blocks that primarily contain form elements, such as contact forms, newsletter signup forms, or login blocks.
Tips
- Use the 'main' role only once per page - it should identify the primary content area
- Every page should ideally have a 'banner' (header) and 'contentinfo' (footer) landmark
- When using multiple blocks with the same role, always add descriptive ARIA labels to differentiate them
- The 'application' role should be used sparingly - only for interactive widgets that require special keyboard handling
- Test your landmark structure using browser accessibility developer tools or screen reader software
- Follow WCAG 2.1 guidelines for proper landmark usage to ensure maximum accessibility compliance
Technical Details
Admin Pages 1
/admin/structure/block/manage/{block_id}
When editing any block, a new collapsible fieldset titled 'Block ARIA Landmark Roles settings' appears. This section allows administrators to configure ARIA landmark roles and labels for the block to improve accessibility.
Hooks 2
hook_form_block_form_alter
Alters the block configuration form to add ARIA landmark role and label fields using third-party settings.
hook_preprocess_block
Preprocesses block variables to add the configured ARIA role and label attributes to the block wrapper element.
Troubleshooting 3
Ensure you have selected a role other than '- None -' and saved the block configuration. Also verify that your theme's block template outputs the $attributes variable, as some custom themes may not include all block attributes.
When you have multiple blocks with the same landmark role (e.g., multiple navigation blocks), always add a unique ARIA label to each one to help screen reader users distinguish between them.
Make sure the Block ARIA Landmark Roles module is enabled. Clear the Drupal cache if you recently enabled it and the fields are not appearing.