next_posts_link() │ WP 0.71

Outputs a link to the next list of posts (for example, the next posts in the category). Navigation within the category.

Used on category (taxonomy) pages.

Since posts are usually sorted in reverse chronological order (the latest post above the previous one), this function outputs a link to the previous posts (i.e., aims towards the beginning of the blog), while previous_posts_link() outputs a link to the page of new posts (aims towards the end of the blog).

Uses: get_next_posts_link()

No Hooks.

Returns

null. Outputs a link to the next page of posts, according to the query.

Usage

<?php next_posts_link( $label , $max_pages ); ?>
$label(string)
Text of the link
Default: 'Next Page »'
$max_pages(int)
Limit, the number of pages on which the link will be shown.

Examples

0

#1 Display a link to the posts next page : 

<?php next_posts_link(); ?>
0

#2 Change the link anchor to "moving on": 

<?php next_posts_link( 'move on', 0 ); ?>
0

#3 Usage when querying the loop with WP_Query

Add the $max_pages parameter to this 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' ) ?: 1;

// the query
$the_query = new WP_Query( [
	'cat'   => 1,
	'paged' => $paged
] );

if ( $the_query->have_posts() ) {

	while ( $the_query->have_posts() ) {
		$the_query->the_post();

		the_title();
	}

	// next_posts_link() usage with max_num_pages.
	next_posts_link( __( 'Older', 'textdomain' ), $the_query->max_num_pages );
	previous_posts_link( __( 'Newer', 'textdomain' ) );

	// Clean up after the query and pagination.
	wp_reset_postdata(); 
}
else {
	?>
	<p><?php _e( 'Sorry, no posts matched your criteria.', 'textdomain' ) ); ?></p>
	<?php
}

Changelog

Since 0.71 Introduced.

next_posts_link() code WP 7.0

wp-includes/link-template.php 
function next_posts_link( $label = null, $max_page = 0 ) {
	echo get_next_posts_link( $label, $max_page );
}

Archives

Posts, Pages, ...