_navigation_markup()WP 4.1.0

Wraps passed links in navigational markup.

This is an internal function for using it by WP core itself. It's not recommended to use this function in your code.

Hooks from the function


String. Navigation template tag.


_navigation_markup( $links, $class, $screen_reader_text, $aria_label );
$links(string) (required)
Navigational links.
Custom class for the nav element.
Default: 'posts-navigation'
Screen reader text for the nav element.
Default: 'Posts navigation'
ARIA label for the nav element.
Default: value of $screen_reader_text



#1 Get a navigation HTML

Let's say we got the navigation links with paginate_links() and now we need to output these links in a standard pagination format:

// get pagination links
$links = paginate_links( $args );

if ( $links ) {
	echo _navigation_markup( $links, 'pagination', 'My cool navigation' );

#2 Changing the navigation/pagination html template

Suppose we want to change the HTML output in functions: the_posts_pagination(), the_posts_navigation(), we need to remove the H2 heading.

To do this, use the hook: navigation_markup_template:

add_filter( 'navigation_markup_template', 'my_navigation_template', 10, 2 );

function my_navigation_template( $template, $class ){
	Type of basic template:
	<nav class="navigation %1$s" role="navigation">
		<h2 class="screen-reader-text">%2$s</h2>
		<div class="nav-links">%3$s</div>

	return '
	<nav class="navigation %1$s" role="navigation">
		<div class="nav-links">%3$s</div>


Since 4.1.0 Introduced.
Since 5.3.0 Added the aria_label parameter.

_navigation_markup() code WP 6.1.1

function _navigation_markup( $links, $class = 'posts-navigation', $screen_reader_text = '', $aria_label = '' ) {
	if ( empty( $screen_reader_text ) ) {
		$screen_reader_text = __( 'Posts navigation' );
	if ( empty( $aria_label ) ) {
		$aria_label = $screen_reader_text;

	$template = '
	<nav class="navigation %1$s" aria-label="%4$s">
		<h2 class="screen-reader-text">%2$s</h2>
		<div class="nav-links">%3$s</div>

	 * Filters the navigation markup template.
	 * Note: The filtered template HTML must contain specifiers for the navigation
	 * class (%1$s), the screen-reader-text value (%2$s), placement of the navigation
	 * links (%3$s), and ARIA label text if screen-reader-text does not fit that (%4$s):
	 *     <nav class="navigation %1$s" aria-label="%4$s">
	 *         <h2 class="screen-reader-text">%2$s</h2>
	 *         <div class="nav-links">%3$s</div>
	 *     </nav>
	 * @since 4.4.0
	 * @param string $template The default template.
	 * @param string $class    The class passed by the calling function.
	 * @return string Navigation template.
	$template = apply_filters( 'navigation_markup_template', $template, $class );

	return sprintf( $template, sanitize_html_class( $class ), esc_html( $screen_reader_text ), $links, esc_html( $aria_label ) );