posts_nav_link() │ WP 0.71

Outputs navigation for post pages — links to the previous and next archive page, if they exist.

May be useful for providing archives with navigation links.

The function is usually placed after the WP_Query loop in archive files (index.php, archive.php, etc.). It automatically outputs HTML links "back/forward" based on the global $wp_query, so no additional settings are required.

Works only on post list pages - in a single post (is_singular()) it will output nothing.

It is only displayed when the number of pages > 1, otherwise it will return an empty string.

Use this function when you need a simple pair of links. In other cases, it is better to use the_posts_navigation() — this is a more modern option.

Difference with the_posts_navigation()

the_posts_navigation() — is a modern, accessibility-friendly wrapper around the same logic of "next/previous archive page", while posts_nav_link() is its minimalist predecessor.

  • HTML structure
    posts_nav_link() — just two links in a row.
    the_posts_navigation() — semantic <nav class="navigation posts-navigation"> + classes for CSS and a11y.

  • Accessibility
    The old function does not add text for screen readers; the new one inserts screen_reader_text.

  • Auto page check
    the_posts_navigation() hides itself if there is one page.
    posts_nav_link() outputs even an empty string, the check needs to be done manually.

Use get_posts_nav_link() to get the result in a variable instead of outputting it to the screen.

To get links to previous/next posts separately use:

Uses: get_posts_nav_link()

No Hooks.

Returns

null.

Usage

<?php posts_nav_link( $sep, $prelabel, $nextlabel ); ?>
$sep(string)
Text displayed between links.
Default: ' — '
$prelabel(string)
Text (anchor) of the link for the previous post.
Default: __('« Previous Page')
$nxtlabel(string)
Text (anchor) of the link for the next post.
Default: __('Next Page »')

Examples

0

#1 HTML that the function outputs 

<?php posts_nav_link( $sep, $prelabel, $nextlabel ); ?>

It will:

<a href="link">« Previous page</a> — <a href="link">Next page »</a>
0

#2 To center it (show it in the middle of the page) use this code: 

<div style="text-align:center;">
	<?php posts_nav_link(' - ', 'Previous page', 'Next page'); ?>
</div>
0

#3 As anchors links can use pictures, such as this: 

<?php
posts_nav_link(
	' ',
	'<img src="' . get_stylesheet_directory_uri() . '/images/prev.jpg" />',
	'<img src="' . get_stylesheet_directory_uri() . '/images/next.jpg" />'
);
?>
0

#4 An alternative to this function

In some cases it's better to use two functions: previous_posts_link() and next_posts_link():

<div class="navigation">
	<div class="alignleft"><?php previous_posts_link( '« Previous Entries' ); ?></div>
	<div class="alignright"><?php next_posts_link( 'Next Entries »', '' ); ?></div>
</div>

Changelog

Since 0.71 Introduced.

posts_nav_link() code WP 6.9.1

wp-includes/link-template.php 
function posts_nav_link( $sep = '', $prelabel = '', $nxtlabel = '' ) {
	$args = array_filter( compact( 'sep', 'prelabel', 'nxtlabel' ) );
	echo get_posts_nav_link( $args );
}

Navigation pagination

Archives

Posts, Pages, ...