next_posts() │ WP 0.71

Gets or displays the URL of the next page of posts.

The function is used in archives, post lists, and other templates with pagination navigation. It receives a link to the next pagination page, for example, older posts.

By default, the function immediately outputs the URL to the screen. If you need to get the URL as a string, pass false as the second parameter.

Important: the function outputs only the URL itself, not the HTML link <a>. For a ready-made link with text, next_posts_link() is usually used.

Uses: get_next_posts_page_link()

Used By: get_next_posts_link()

No Hooks.

Returns

String|null.

string — URL of the next page of posts (when $display = false).
'' (empty string) — if there is no next page.
void — if $display = true — outputs the URL and returns nothing.

Usage

next_posts( $max_page, $display );

$max_page(int): Maximum number of pages. If you specify 0, WordPress uses the value from the main query.
Default: 0
$display(bool): Determines whether to immediately output the URL.
Default: true

Examples

#1 Output URL of the next page

The function will immediately output the URL of the next page of posts.

next_posts(); // https://example.com/...

#2 Getting the URL without output

In this example, the URL is saved to a variable so it can be used later.

$next_posts_url = next_posts( 0, false );

if ( $next_posts_url ) {
	echo esc_url( $next_posts_url );
}

#3 Creating your own HTML link

Since the function only gets the URL, you can make the HTML markup manually.

if ( $next_posts_url ) {
	printf( '<a href="%s">Old Posts</a>', next_posts( 0, false ) );
}

#4 Maximum Number of Pages Limit

In this example the link will be obtained only within the specified number of pages.

$max_page       = 5;
$next_posts_url = next_posts( $max_page, false );

if ( $next_posts_url ) {
	printf( '<a href="%s">Next page</a>', esc_url( $next_posts_url ) );
}

Changelog

Since 0.71

Introduced.

`next_posts() next posts` code ^{WP 7.0}

wp-includes/link-template.php

function next_posts( $max_page = 0, $display = true ) {
	$link   = get_next_posts_page_link( $max_page );
	$output = $link ? esc_url( $link ) : '';

	if ( $display ) {
		echo $output;
	} else {
		return $output;
	}
}