the_posts_pagination()
Outputs pagination links to the next/previous set of posts. Uses for archives pages (categories, tags, etc...).
The function is designed to be used with any post type.
Use get_the_posts_pagination() to get a result for further processing.
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 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, ) ); ?>
#2 'end_size' parameter
Let's set 2 links to the last pages in the pagination:
<?php the_posts_pagination( array( 'end_size' => 2, ) ); ?>
#3 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, ) );
#4 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>
Changelog
Since 4.1.0 | Introduced. |
the_posts_pagination() the posts pagination code WP 6.6.2
function the_posts_pagination( $args = array() ) { echo get_the_posts_pagination( $args ); }