Using WordPress ‘get_the_posts_pagination()’ PHP function

by

The get_the_posts_pagination() WordPress PHP function retrieves a paginated navigation to the next/previous set of posts, when applicable.

Usage

echo get_the_posts_pagination( array(
    'mid_size' => 2,
    'prev_text' => __( 'Back', 'textdomain' ),
    'next_text' => __( 'Next', 'textdomain' ),
) );

Parameters

  • $args (array) Optional: Default pagination arguments.
    • screen_reader_text (string): Screen reader text for navigation element. Default ‘Posts navigation’.
    • aria_label (string): ARIA label text for the nav element. Default ‘Posts’.
    • class (string): Custom class for the nav element. Default ‘pagination’.
  • More Arguments from paginate_links( … $args ):
    • base (string): Base of the paginated URL.
    • format (string): Format for the pagination structure.
    • total (int): The total amount of pages. Default is the value WP_Query’s max_num_pages or 1.
    • current (int): The current page number. Default is ‘paged’ query var or 1.
    • aria_current (string): The value for the aria-current attribute. Possible values are ‘page’, ‘step’, ‘location’, ‘date’, ‘time’, ‘true’, ‘false’. Default is ‘page’.
    • show_all (bool): Whether to show all pages. Default false.
    • end_size (int): How many numbers on either the start and the end list edges. Default 1.
    • mid_size (int): How many numbers to either side of the current pages. Default 2.
    • prev_next (bool): Whether to include the previous and next links in the list. Default true.
    • prev_text (string): The previous page text. Default ‘« Previous’.
    • next_text (string): The next page text. Default ‘Next »’.
    • type (string): Controls format of the returned value. Possible values are ‘plain’, ‘array’, and ‘list’. Default is ‘plain’.
    • add_args (array): An array of query args to add. Default false.
    • add_fragment (string): A string to append to each link.
    • before_page_number (string): A string to appear before the page number.
    • after_page_number (string): A string to append after the page number.

More information

See WordPress Developer Resources: get_the_posts_pagination

Examples

Basic usage

Display the default pagination for posts.

echo get_the_posts_pagination();

Customizing mid_size

Display pagination with 3 numbers to either side of the current page.

echo get_the_posts_pagination( array(
    'mid_size' => 3,
) );

Custom previous and next text

Change the previous and next page text to custom text.

echo get_the_posts_pagination( array(
    'prev_text' => __( 'Go Back', 'textdomain' ),
    'next_text' => __( 'Go Forward', 'textdomain' ),
) );

Remove the previous and next links from the pagination.

echo get_the_posts_pagination( array(
    'prev_next' => false,
) );