Title: get_the_posts_pagination Published: December 18, 2014 Last modified: August 20, 2026 --- # get_the_posts_pagination( array $args = array() ): string ## In this article * [Parameters](https://developer.wordpress.org/reference/functions/get_the_posts_pagination/?output_format=md#parameters) * [Return](https://developer.wordpress.org/reference/functions/get_the_posts_pagination/?output_format=md#return) * [Source](https://developer.wordpress.org/reference/functions/get_the_posts_pagination/?output_format=md#source) * [Hooks](https://developer.wordpress.org/reference/functions/get_the_posts_pagination/?output_format=md#hooks) * [Related](https://developer.wordpress.org/reference/functions/get_the_posts_pagination/?output_format=md#related) * [Changelog](https://developer.wordpress.org/reference/functions/get_the_posts_pagination/?output_format=md#changelog) * [User Contributed Notes](https://developer.wordpress.org/reference/functions/get_the_posts_pagination/?output_format=md#user-contributed-notes) [ Back to top](https://developer.wordpress.org/reference/functions/get_the_posts_pagination/?output_format=md#wp--skip-link--target) Retrieves a paginated navigation to next/previous set of posts, when applicable. ## 󠀁[Parameters](https://developer.wordpress.org/reference/functions/get_the_posts_pagination/?output_format=md#parameters)󠁿 `$args`arrayoptional Default pagination arguments, see [paginate_links()](https://developer.wordpress.org/reference/functions/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. * `format` string * Format for the pagination structure. * `total` int * The total amount of pages. Default is the value [WP_Query](https://developer.wordpress.org/reference/classes/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. Default:`array()` ## 󠀁[Return](https://developer.wordpress.org/reference/functions/get_the_posts_pagination/?output_format=md#return)󠁿 string Markup for pagination links. ## 󠀁[Source](https://developer.wordpress.org/reference/functions/get_the_posts_pagination/?output_format=md#source)󠁿 ```php 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](https://developer.wordpress.org/reference/files/wp-includes/link-template.php/) [View on Trac](https://core.trac.wordpress.org/browser/tags/7.1/src/wp-includes/link-template.php#L2949) [View on GitHub](https://github.com/WordPress/wordpress-develop/blob/7.1/src/wp-includes/link-template.php#L2949-L3003) ## 󠀁[Hooks](https://developer.wordpress.org/reference/functions/get_the_posts_pagination/?output_format=md#hooks)󠁿 [apply_filters( ‘the_posts_pagination_args’, array $args )](https://developer.wordpress.org/reference/hooks/the_posts_pagination_args/) Filters the arguments for posts pagination links. ## 󠀁[Related](https://developer.wordpress.org/reference/functions/get_the_posts_pagination/?output_format=md#related)󠁿 | Uses | Description | | [_navigation_markup()](https://developer.wordpress.org/reference/functions/_navigation_markup/)`wp-includes/link-template.php` | Wraps passed links in navigational markup. | | [paginate_links()](https://developer.wordpress.org/reference/functions/paginate_links/)`wp-includes/general-template.php` | Retrieves paginated links for archive post pages. | | [_x()](https://developer.wordpress.org/reference/functions/_x/)`wp-includes/l10n.php` | Retrieves translated string with gettext context. | | [__()](https://developer.wordpress.org/reference/functions/__/)`wp-includes/l10n.php` | Retrieves the translation of $text. | | [wp_parse_args()](https://developer.wordpress.org/reference/functions/wp_parse_args/)`wp-includes/functions.php` | Merges user defined arguments into defaults array. | | [apply_filters()](https://developer.wordpress.org/reference/functions/apply_filters/)`wp-includes/plugin.php` | Calls the callback functions that have been added to a filter hook. | [Show 4 more](https://developer.wordpress.org/reference/functions/get_the_posts_pagination/?output_format=md#) [Show less](https://developer.wordpress.org/reference/functions/get_the_posts_pagination/?output_format=md#) | Used by | Description | | [the_posts_pagination()](https://developer.wordpress.org/reference/functions/the_posts_pagination/)`wp-includes/link-template.php` | Displays a paginated navigation to next/previous set of posts, when applicable. | ## 󠀁[Changelog](https://developer.wordpress.org/reference/functions/get_the_posts_pagination/?output_format=md#changelog)󠁿 | Version | Description | | [5.5.0](https://developer.wordpress.org/reference/since/5.5.0/) | Added the `class` parameter. | | [5.3.0](https://developer.wordpress.org/reference/since/5.3.0/) | Added the `aria_label` parameter. | | [4.1.0](https://developer.wordpress.org/reference/since/4.1.0/) | Introduced. | ## 󠀁[User Contributed Notes](https://developer.wordpress.org/reference/functions/get_the_posts_pagination/?output_format=md#user-contributed-notes)󠁿 1. [Skip to note 3 content](https://developer.wordpress.org/reference/functions/get_the_posts_pagination/?output_format=md#comment-content-2838) 2. [Nilo Velez](https://profiles.wordpress.org/nilovelez/) [ 8 years ago ](https://developer.wordpress.org/reference/functions/get_the_posts_pagination/#comment-2838) 3. [You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fget_the_posts_pagination%2F%23comment-2838) Vote results for this note: 3[You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fget_the_posts_pagination%2F%23comment-2838) 4. `$args` param is passed to the [paginate_links()](https://codex.wordpress.org/Function_Reference/paginate_links) function. 5. Default values: 6. ```php '%_%', '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' => '' ); ?> ``` 7. [Log in to add feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fget_the_posts_pagination%2F%3Freplytocom%3D2838%23feedback-editor-2838) 8. [Skip to note 4 content](https://developer.wordpress.org/reference/functions/get_the_posts_pagination/?output_format=md#comment-content-2197) 9. [Mizner](https://profiles.wordpress.org/mizner/) [ 9 years ago ](https://developer.wordpress.org/reference/functions/get_the_posts_pagination/#comment-2197) 10. [You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fget_the_posts_pagination%2F%23comment-2197) Vote results for this note: 2[You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fget_the_posts_pagination%2F%23comment-2197) 11. ```php // Usage Example $pagination = get_the_posts_pagination( array( 'mid_size' => 2, 'prev_text' => __( 'Newer', 'textdomain' ), 'next_text' => __( 'Older', 'textdomain' ), ) ); ``` 12. [Log in to add feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fget_the_posts_pagination%2F%3Freplytocom%3D2197%23feedback-editor-2197) You must [log in](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fget_the_posts_pagination%2F) before being able to contribute a note or feedback.