get_posts_nav_link() │ WP 2.8.0

Gets links to the previous and next pages of posts on the archive page (category/tag/author).

Used to insert pagination links (< back - forward >) for archive pages.

When you need to display the result on the screen, use posts_nav_link()

Uses: get_previous_posts_link(), get_next_posts_link()

Used By: posts_nav_link()

No Hooks.

Returns

String. HTML navigation links for archive pages.

Usage

$links_html = get_posts_nav_link( $args );

$args(string/array)

Parameters for creating navigation links.

sep(string)
Text between links - separator.
Default: '—'
prelabel(string)
Text (anchor) for the previous post link.
Default: __('« Previous Page')
nxtlabel(string)
Text (anchor) for the next post link.
Default: __('Next Page »')

Default: array()

Examples

#1 Demonstration of what the function outputs

echo get_posts_nav_link();

Displays:

<a href="link">Previous page</a> - <a href="link">Next page"</a>

#2 Place the links in the middle and pass the parameters

To do this, wrap them in a DIV and give it the text-align:center property:

$links_html = get_posts_nav_link( array(
	'sep' => ' . ',
	'prelabel' => 'Previous page',
	'nxtlabel' => 'Next page'
) );

echo "<div style='text-align:center;'>$links_html</div>";

#3 Instead of texts: "Previous page", "Next page", you can use images

$links_html = get_posts_nav_link( array(
	'sep' => ' . ',
	'prelabel' => '<img src="' . get_stylesheet_directory_uri() . '/images/prev.jpg" />',
	'nxtlabel' => '<img src="' . get_stylesheet_directory_uri() . '/images/next.jpg" />'
) );

Notes

Global. WP_Query. $wp_query WordPress Query object.

Changelog

Since 2.8.0

Introduced.

`get_posts_nav_link() get posts nav link` code ^{WP 7.0.2}

wp-includes/link-template.php

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

	$return = '';

	if ( ! is_singular() ) {
		$defaults = array(
			'sep'      => ' &#8212; ',
			'prelabel' => __( '&laquo; Previous Page' ),
			'nxtlabel' => __( 'Next Page &raquo;' ),
		);
		$args     = wp_parse_args( $args, $defaults );

		$max_num_pages = $wp_query->max_num_pages;
		$paged         = get_query_var( 'paged' );

		// Only have sep if there's both prev and next results.
		if ( $paged < 2 || $paged >= $max_num_pages ) {
			$args['sep'] = '';
		}

		if ( $max_num_pages > 1 ) {
			$return  = get_previous_posts_link( $args['prelabel'] );
			$return .= preg_replace( '/&([^#])(?![a-z]{1,8};)/i', '&#038;$1', $args['sep'] );
			$return .= get_next_posts_link( $args['nxtlabel'] );
		}
	}
	return $return;
}