When lists of links are displayed on a page for navigational purpose, it can become difficult for users utilizing assistive technologies to navigate between these lists while maintaining an understanding of the purpose of the links. The <ul> element also does not convey proper context.

Starting in WordPress 5.5, a new theme support feature (navigation-widgets) has been added to address this issue. When support is declared, all default widgets included in WordPress CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. that produce lists of links will be output wrapped in the <nav> element. Note: the markup produced inside this wrapper will remain unchanged.

Additionally, an aria-label attribute (which is spoken to users using assistive technologies) is automatically generated based on the widgetWidget A WordPress Widget is a small block that performs a specific function. You can add these widgets in sidebars also known as widget-ready areas on your web page. WordPress widgets were originally created to provide a simple and easy-to-use way of giving design and structure control of the WordPress theme to the user.’s title field and added to the nav element to help distinguish each navigation widget from other nav elements on the page (such as a primary navigation).

The feature is fully opt-in. Theme developers must declare HTML5 support for navigation-widgets. For many themes, this may need some additional CSSCSS Cascading Style Sheets. rules or adjustments to ensure the widgets remain properly styled when outputting the new markup.

Theme developers are highly encouraged to utilize this improvement in their themes. This new theme support feature is an easy way to improve semantics and accessibilityAccessibility Accessibility (commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology (for example, computer screen readers). (https://en.wikipedia.org/wiki/Accessibility) in all of the sites using your theme.

Widgets affected

The following default Core widgets are impacted by this change:

• Navigation menuNavigation Menu A theme feature introduced with Version 3.0. WordPress includes an easy to use mechanism for giving various control options to get users to click from one place to another on a site.
• Archives
• Categories
• Pages
• Recent posts
• Recent comments
• MetaMeta Meta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress.
• RSS

How to declare support

Theme developers are encouraged to declare support for navigation widgets in their functions.php file. This can be done by calling add_theme_support() and passing the preexisting html5 feature with the new navigation-widgets type.

Example

// Declare support for navigation widgets markup.
add_theme_support( 'html5', array( 'navigation-widgets' ) );

// This can be combined with other HTML5 types if supported.
add_theme_support(
	'html5',
	array(
		'navigation-widgets',
		'comment-list',
		'comment-form',
		'search-form',
		'gallery',
		'caption',
		'style',
		'script'
	)
);

For reference, see the related documentation on DevHub.

As mentioned above, an aria-label will be generated for each widget based on the widget’s “Title” field. Below is a screenshot when aria-label attributes are not present to illustrate the problem for users utilizing a screen reader.

The screenshot below shows how the user’s experience is improved when by aria-label attributes.

Markup changes

Below is what the output markup looks like when support for navigation-widgets is not declared.

<!-- Without declaration for HTML5 `navigation-widgets` feature support -->
<div class="widget widget_archive">
	<div class="widget-content">
		<h2 class="widget-title">Archives</h2>
		<ul>
			<li><a href="mywebsite/2020/07/">July 2020</a></li>
			<li><a href="mywebsite/2019/12/">December 2019</a></li>
		</ul>
	</div>
</div>

Below is what the new output markup will look like when support for navigation-widgets is declared.

<!-- When the theme declares HTML5 `navigation-widgets` feature support -->
<div class="widget widget_archive">
	<div class="widget-content">
		<h2 class="widget-title">Archives</h2>
		<nav role="navigation" aria-label="Archives">
			<ul>
				<li><a href="mywebsite/2020/07/">July 2020</a></li>
				<li><a href="mywebsite/2019/12/">December 2019</a></li>
			</ul>
		</nav>
	</div>
</div>

Forcing navigation-widgets support

Support for HTML5 navigation-widgets feature can be forced on a site by using the new navigation_widgets_format filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output.. This hook determines the type of markup used in widgets that contain navigation links.

This filter accepts two different values: html5 and xhtml. Returning any other value to this filter will output the old markup without these accessibility improvements.

// Force HTML5 markup.
function mytheme_force_semantic_nav_widgets( $value ) {
	return 'html5';
}
add_filter( 'navigation_widgets_format', 'mytheme_force_semantic_nav_widgets');

// Force legacy markup.
function mytheme_force_legacy_nav_widgets( $value ) {
	return 'xhmtl';
}
add_filter( 'navigation_widgets_format', 'mytheme_force_legacy_nav_widgets');

For reference, see the related TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress. ticketticket Created for both bug reports and feature development on the bug tracker.: #48170.

Props @whyisjake and @desrosj for proofreading.

#5-5, #accessibility, #dev-notes, #html5, #widgets