WordPress.org

Ready to get started?Download WordPress

Codex

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

Function Reference/next posts link

Contents

Description

Prints a link to the next set of posts within the current query.

If you need the values for use in PHP, use get_next_posts_link().

Because post queries are usually sorted in reverse chronological order, next_posts_link() usually points to older entries (toward the end of the set) and previous_posts_link() usually points to newer entries (toward the beginning of the set).

Usage

 <?php next_posts_link$label $max_pages ); ?> 

Parameters

$label
(string) (optional) The link text.
Default: 'Next Page »'
$max_pages
(integer) (optional) Limit the number of pages on which the link is displayed. The default value "0" means "no limit".
Default: 0

Examples

Default Usage

<?php next_posts_link(); ?>

Working example

<?php next_posts_link('Older Entries »', 0); ?>


Usage when querying the loop with WP_Query

Add the $max_pages parameter to the next_posts_link() function when querying the loop with WP_Query. To get the total amount of pages you can use the 'max_num_pages' property of the custom WP_Query object.

<?php
// set the "paged" parameter (use 'page' if the query is on a static front page)
$paged = ( get_query_var( 'paged' ) ) ? get_query_var( 'paged' ) : 1;

// the query
$the_query = new WP_Query( 'cat=1&paged=' . $paged ); 
?>

<?php if ( $the_query->have_posts() ) : ?>

<?php
// the loop
while ( $the_query->have_posts() ) : $the_query->the_post(); 
?>
<?php the_title(); ?>
<?php endwhile; ?>

<?php

// next_posts_link() usage with max_num_pages
next_posts_link( 'Older Entries', $the_query->max_num_pages );
previous_posts_link( 'Newer Entries' );
?>

<?php 
// clean up after the query and pagination
wp_reset_postdata(); 
?>

<?php else:  ?>
<p><?php _e( 'Sorry, no posts matched your criteria.' ); ?></p>
<?php endif; ?>

Notes

  • This function will not work (fail silently) if mysql.trace_mode is enabled in your php.ini. If you can't edit that file, try adding ini_set( 'mysql.trace_mode', 0 ); to your theme's functions.php.
  • This function does not work with static pages.

Resources

Change Log

Since: 0.71

Source File

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

Related

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