the_posts_pagination() │ WP 4.1.0

Outputs pagination links to the next/previous set of posts. Uses for archives pages (categories, tags, etc...).

pagination links in the Twenty Fifteen theme

The function is designed to be used with any post type.

Use get_the_posts_pagination() to get a result for further processing.

Uses: get_the_posts_pagination()

No Hooks.

Return

null. Nothing. Outputs the HTML code of the pagination. If there are no pagination pages (less than 1), it outputs nothing.

Usage

the_posts_pagination( $args );

$args(array)

Parameters by which the result will be displayed. Default:

$args = array(
	'show_all' => false, // all pages involved in pagination are shown
	'end_size' => 1,     // number of pages at the ends
	'mid_size' => 1,     // number of pages around the current page
	'prev_next' => true, // whether to display 'previous/next page' side links.
	'prev_text' => __(''Previous'),
	'next_text' => __('Next "),
	'add_args' => false,  // Array of arguments (query variables) to add to links.
	'add_fragment' => '', // Text to be added to all links.
	'screen_reader_text' => __('Posts navigation' ),
);

This parameter is passed to the paginate_links() function, so see its description for a complete list of parameters.

See get_the_posts_pagination() for available arguments.

Default: array() - presets

Examples

#1 Removing H2 header from the template

By default the pagination template contains a hidden tag H2, which is added for screen readers (this is a program for the visually impaired, which help to orient to the site page by sound).

In terms of SEO, this tag seems to be better to remove. You can do this with the filter navigation_markup_template:

// removes H2 from the pagination 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>
	</nav>
	*/

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

// output the pagination
the_posts_pagination( array(
	'end_size' => 2,
) );

#2 Display the pagination on the screen

<?php the_posts_pagination(); ?>

Outputs:

<nav class="navigation pagination" role="navigation">
	<h2 class="screen-reader-text">Navigating Through Posts</h2>
	<div class="nav-links"><span class="page-numbers current"><span class="meta-nav screen-reader-text">Page </span>1</span>
		<a class="page-numbers" href="http://wptest.com/page/2/"><span class="meta-nav screen-reader-text">Page </span>2</a>
		<span class="page-numbers dots">…</span>
		<a class="page-numbers" href="http://wptest.com/page/86/"><span class="meta-nav screen-reader-text">Page </span>86</a>
		<a class="page-numbers" href="http://wptest.com/page/87/"><span class="meta-nav screen-reader-text">Page </span>87</a>
		<a class="next page-numbers" href="http://wptest.com/page/2/">Next page</a>
	</div>
</nav>

pagination links in the Twenty Fifteen theme

#3 Controlling the display

By default, the_posts_pagination() outputs the first and last page and one page each around the current page. The rest are replaced by ellipses. This output can be changed with arguments:

show_all - show all pages.
end_size - the number of pages at the beginning and at the end of the list.
mid_size - number of pages to the left and right of the current page.

<?php
the_posts_pagination( array(
	'mid_size' => 2,
) );
?>

#4 'end_size' parameter

Let's set 2 links to the last pages in the pagination:

<?php
the_posts_pagination( array(
	'end_size' => 2,
) );
?>

Changelog

Since 4.1.0

Introduced.

`the_posts_pagination() the posts pagination` code ^{WP 6.1.1}

wp-includes/link-template.php

function the_posts_pagination( $args = array() ) {
	echo get_the_posts_pagination( $args );
}