WordPress.org

Codex

Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Function Reference/posts nav link

Description

Displays links for next and previous pages. Useful for providing "paged" navigation of index, category and archive pages.

For displaying next and previous pages of posts see next_posts_link() and previous_posts_link().

For displaying next and previous post navigation on individual posts, see next_post_link() and previous_post_link().

Usage

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

Note: since weblog posts are traditionally listed in reverse chronological order (with most recent posts at the top), there is some ambiguity in the definition of "next page". WordPress defines "next page" as the "next page toward the past". In WordPress 1.5, the default Kubrick theme addresses this ambiguity by labeling the "next page" link as "previous entries". See Example: Kubrick Theme Format.

Parameters

$sep 
(string) Text displayed between the links.
  • Defaults to ' :: ' in 1.2.x.
  • Defaults to ' — ' in 1.5.
$prelabel 
(string) Link text for the previous page.
  • Defaults to '<< Previous Page' in 1.2.x.
  • Defaults to '« Previous Page' in 1.5.
$nxtlabel 
(string) Link text for the next page.
  • Defaults to 'Next Page >>' in 1.2.x.
  • Defaults to 'Next Page »' in 1.5

Examples

Default Usage

By default, the posts_nav_link() look like this:

« Previous PageNext Page »
<?php posts_nav_link(); ?>

In Centered DIV

Displays previous and next page links ("previous page · next page") centered on the page.

<div style="text-align:center;">
<?php posts_nav_link( ' &#183; ', 'previous page', 'next page' ); ?>
</div>

Using Images

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

Kubrick Theme Format

The Kubrick theme format for posts navigation, could be formatted this way. However, using posts_nav_link() in this way will result in unintended behavior, such as double stacked next and previous links that link to the incorrect sections.

The Kubrick Theme actually uses next_posts_link() and previous_posts_link().

This is poor code and should not be used:

<div class="navigation">
<div class="alignleft"><?php posts_nav_link( '', '', '&laquo; Previous Entries' ); ?></div>
<div class="alignright"><?php posts_nav_link( '', 'Next Entries &raquo;', '' ); ?></div>
</div>

This is better code:

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

Customizing the Link Text

You can change the text in each of the links and in the text in between the links.

You can go back to the previous page or you can go forward to the next page.
<p><?php posts_nav_link( ' or ', 'You can go back to the previous page', 'you can go forward to the next page' ); ?>.</p>

Resources

Changelog

Since: 2.8.0

Source File

posts_nav_link() is located in wp-includes/link-template.php.

Related

See also index of Function Reference and index of Template Tags.