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

Displays the next posts page link.

Contents

Parameters

$label string Optional
Content for link text.

Default: null

$max_page int Optional
Max pages. Default 0.

Top ↑

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() .

Top ↑

Source

File: wp-includes/link-template.php. View all references 

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

View on Trac View on GitHub

Top ↑

Top ↑

Changelog

Changelog
Version Description
0.71 Introduced.

Top ↑

User Contributed Notes

  1. Skip to note 1 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 3You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    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 2 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note
    Contributed by Code Amp —

    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.