next_posts_link( string $label = null, int $max_page )

Displays the next posts page link.

Parameters

$labelstringoptional
Content for link text.

Default:null

$max_pageintoptional
Max pages. Default 0.

More Information

This function 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).

Parameter $max_pages is the limit the number of pages on which the link is displayed. The default value “0” means “no limit”.

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.

See also: previous_posts_link() and next_post_link().

Source

function next_posts_link( $label = null, $max_page = 0 ) {
	echo get_next_posts_link( $label, $max_page );
}

Changelog

VersionDescription
0.71Introduced.

User Contributed Notes

  1. Skip to note 5 content

    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.

    // 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( array(
    	'cat'   => 1,
    	'paged' => $paged
    );
    
    if ( $the_query->have_posts() ) :
    	// the loop
    	while ( $the_query->have_posts() ) : $the_query->the_post();
    		the_title();
    		
    	endwhile;
    
    	// next_posts_link() usage with max_num_pages.
    	next_posts_link( __( 'Older Entries', 'textdomain' ), $the_query->max_num_pages );
    	previous_posts_link( __( 'Newer Entries', 'textdomain' ) );
    
    	// Clean up after the query and pagination.
    	wp_reset_postdata(); 
    
    else:
    	?>
    	<p><?php _e( 'Sorry, no posts matched your criteria.', 'textdomain' ) ); ?></p>
    	<?php
    endif;
  2. Skip to note 6 content

    A warning when using with custom queries

    This function next_posts_link() has a condition to run if is_single() is false.

    This is good to know when creating custom queries and adding pagination using this function because where you place your custom query can change whether the pagination shows or not.

    What’s interesting is that:
    is_single() doesn’t work on pages (or media)
    is_single() does work on CPTs and posts

    So custom queries with this pagination placed on a single page will work fine, but add the same custom query + pagination to a single CPT or post, and it will not show.

You must log in before being able to contribute a note or feedback.