get_the_posts_pagination() – Function

Retrieves a paginated navigation to next/previous set of posts, when applicable.

Parameters

$argsarrayoptional

Default pagination arguments, see paginate_links() .

screen_reader_text string
Screen reader text for navigation element.
Default ‘Posts pagination’.
aria_label string
ARIA label text for the nav element. Default ‘Posts pagination’.
class string
Custom class for the nav element. Default 'pagination'.

More Arguments from paginate_links( … $args )

Array or string of arguments for generating paginated links for archives.

base string
Base of the paginated url. Default empty.
format string
Format for the pagination structure. Default empty.
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. Default empty.
before_page_number string
A string to appear before the page number. Default empty.
after_page_number string
A string to append after the page number. Default empty.

Default:array()

Return

string Markup for pagination links.

Source

function get_the_posts_pagination( $args = array() ) {
	global $wp_query;

	$navigation = '';

	// Don't print empty markup if there's only one page.
	if ( $wp_query->max_num_pages > 1 ) {
		// Make sure the nav element has an aria-label attribute: fallback to the screen reader text.
		if ( ! empty( $args['screen_reader_text'] ) && empty( $args['aria_label'] ) ) {
			$args['aria_label'] = $args['screen_reader_text'];
		}

		$args = wp_parse_args(
			$args,
			array(
				'mid_size'           => 1,
				'prev_text'          => _x( 'Previous', 'previous set of posts' ),
				'next_text'          => _x( 'Next', 'next set of posts' ),
				'screen_reader_text' => __( 'Posts pagination' ),
				'aria_label'         => __( 'Posts pagination' ),
				'class'              => 'pagination',
			)
		);

		/**
		 * Filters the arguments for posts pagination links.
		 *
		 * @since 6.1.0
		 *
		 * @param array $args {
		 *     Optional. Default pagination arguments, see paginate_links().
		 *
		 *     @type string $screen_reader_text Screen reader text for navigation element.
		 *                                      Default 'Posts navigation'.
		 *     @type string $aria_label         ARIA label text for the nav element. Default 'Posts'.
		 *     @type string $class              Custom class for the nav element. Default 'pagination'.
		 * }
		 */
		$args = apply_filters( 'the_posts_pagination_args', $args );

		// Make sure we get a string back. Plain is the next best thing.
		if ( isset( $args['type'] ) && 'array' === $args['type'] ) {
			$args['type'] = 'plain';
		}

		// Set up paginated links.
		$links = paginate_links( $args );

		if ( $links ) {
			$navigation = _navigation_markup( $links, $args['class'], $args['screen_reader_text'], $args['aria_label'] );
		}
	}

	return $navigation;
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘the_posts_pagination_args’, array $args ): Filters the arguments for posts pagination links.

Uses	Description
_navigation_markup()`wp-includes/link-template.php`	Wraps passed links in navigational markup.
paginate_links()`wp-includes/general-template.php`	Retrieves paginated links for archive post pages.
_x()`wp-includes/l10n.php`	Retrieves translated string with gettext context.
__()`wp-includes/l10n.php`	Retrieves the translation of $text.
wp_parse_args()`wp-includes/functions.php`	Merges user defined arguments into defaults array.
apply_filters()`wp-includes/plugin.php`	Calls the callback functions that have been added to a filter hook.

Show 4 more Show less

Used by	Description
the_posts_pagination()`wp-includes/link-template.php`	Displays a paginated navigation to next/previous set of posts, when applicable.

Changelog

Version	Description
5.5.0	Added the `class` parameter.
5.3.0	Added the `aria_label` parameter.
4.1.0	Introduced.

User Contributed Notes

Nilo Velez 8 years ago

$args param is passed to the paginate_links() function.

Default values:

<?php $args = array(
	'base'               => '%_%',
	'format'             => '?paged=%#%',
	'total'              => 1,
	'current'            => 0,
	'show_all'           => false,
	'end_size'           => 1,
	'mid_size'           => 2,
	'prev_next'          => true,
	'prev_text'          => __('« Previous'),
	'next_text'          => __('Next »'),
	'type'               => 'plain',
	'add_args'           => false,
	'add_fragment'       => '',
	'before_page_number' => '',
	'after_page_number'  => ''
); ?>

Skip to note 4 content

Mizner 9 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note
```
// Usage Example
$pagination = get_the_posts_pagination( array(
    'mid_size' => 2,
    'prev_text' => __( 'Newer', 'textdomain' ),
    'next_text' => __( 'Older', 'textdomain' ),
) );
```
Log in to add feedback

get_the_posts_pagination( array $args = array() ): string

In this article