How to use the the_posts_pagination() function in WordPress

Do you want to stop having to add WordPress pagination links by hand? Fortunately, WordPress has an in-built feature for managing pagination automatically, which makes it much simpler than ever to set up intuitive page navigation. In this article, we’ll learn about the the_posts_pagination() function, describe its uses, and outline the parameters you can pass to it.

What is the the_posts_pagination() function?

The the_posts_pagination() function is an integral part of WordPress, and it is responsible for generating pagination links for the blog posts on your website. It provides a simple method for separating your content across numerous pages, which makes it easier for your visitors to explore your website.

Using the_posts_pagination() function

To use the the_posts_pagination() function, simply place the following code within your WordPress theme’s loop, usually located in the ‘index.php’, ‘archive.php’, or ‘search.php’ (assuming you are using this in a custom theme) template files:

if ( have_posts() ) :
    while ( have_posts() ) : the_post();
        // Your code to display each post

This code checks if there are any posts to display, and if so, it loops through them and displays each post. After the loop, it calls the the_posts_pagination() function to display the pagination links.

Customising the_posts_pagination() with Arguments

The the_posts_pagination() function can accept an array of arguments, allowing you to modify the appearance and behavior of the pagination links. Here are some of the most commonly used arguments:

  • ‘prev_text’ (string) – The text for the previous page link. Default is ‘Previous’.
  • ‘next_text’ (string) – The text for the next page link. Default is ‘Next’.
  • ‘screen_reader_text’ (string) – The text for screen readers. Default is ‘Posts navigation’.
  • ‘before_page_number’ (string) – Text to insert before the page number. Default is an empty string.
  • ‘after_page_number’ (string) – Text to insert after the page number. Default is an empty string.
  • ‘mid_size’ (integer) – The number of page links to display around the current page. Default is 2.
  • ‘end_size’ (integer) – The number of page links to display at the beginning and end of the pagination. Default is 1.

To use these arguments, pass an array with the desired key-value pairs to the_posts_pagination() function:

the_posts_pagination( array(
    'prev_text'          => __( '<< Previous', 'your-theme' ),
    'next_text'          => __( 'Next >>', 'your-theme' ),
    'screen_reader_text' => __( 'Post Navigation', 'your-theme' ),
    'before_page_number' => '<span class="meta-nav screen-reader-text">' . __( 'Page', 'your-theme' ) . ' </span>',
    'after_page_number'  => '',
    'mid_size'           => 3,
    'end_size'           => 2,
) );

In this particular depiction, we have modified the text that is displayed for the previous and next page links, as well as the text that is read aloud by the screen reader. Furthermore, we have altered the number of page links that are displayed all around the currently active page, as well as at the beginning and end of the pagination.

Wrapping it up

When it comes to handling the pagination on your WordPress website, the the_posts_pagination() function is an extremely strong and versatile tool. You will be able to create a smooth experience for your users if you understand the many possible parameters that may be passed to the pagination link and then personalise its design and behaviour. Enhance the navigation on your website by getting started with the the_posts_pagination() function right away!