paginate_comments_links() │ WP 2.7.0

Outputs a list of links to the comment pages (pagination links) of the current post.

Since version 2.7, the WordPress developers simplified the comment template (file comments.php) to make it easier to create and edit the display of comments. One of these improvements was the ability to paginate comments, so visitors no longer need to load hundreds of comments on one page, but can instead have pagination for comments.

To enable comment pagination, you can do so on the admin panel page Settings > Discussion.

Once pagination is enabled in the system, the navigation links for the comment pages can be output with the following code:

<?php paginate_comments_links(); ?>

The equivalent of such pagination are the functions next_comments_link() and previous_comments_link(), which output links to the next and previous comment pages.

Almost the same analogous function: the_comments_pagination()

Uses: paginate_links()

Used By: get_the_comments_pagination()

No Hooks.

Returns

null|String|Array.

Nothing - if the parameter echo = true and type is not array. Or when the function is called not on a post page (i.e., there can be no comments on the page).
HTML pagination links when echo = false.
An array of pagination links when type = array|plain|list.

Usage Template

paginate_comments_links( [
	'base'    => add_query_arg( 'cpage', '%#%' ),
	'format'  => null,
	'total'   => $max_page,
	'current' => $page,
	'echo'    => true,
	'add_fragment' => '#comments',
] );

Usage

<?php paginate_comments_links( $args ) ?>

$args(string/array)

Arguments based on which the result will be obtained.

See the parameter descriptions in the function paginate_links(), which is the core of this function.

Default: presets

Examples

#1 Output page navigation of comments

If the WP settings are set to "separate comments into pages", then the template uses this code to display the navigation:

<div class="navigation"><?php paginate_comments_links( $args ) ?></div>

We end up with a code like this:

<div class="navigation">
	<a class="prev page-numbers" href="/id_140/comment-page-3#comments">«««</a>
	<a class='page-numbers' href='/id_140/comment-page-1#comments'>1</a>
	<a class='page-numbers' href='/id_140/comment-page-2#comments'>2</a>
	<a class='page-numbers' href='/id_140/comment-page-3#comments'>3</a>
	<span class='page-numbers current'>4</span>
</div>

#2 Changing the text of "next/previous page" links

To change the text of the next/previous page links, you must pass the arguments prev_text and next_text

paginate_comments_links( 'prev_text=back&next_text=forward' )

If you want to use special html symbols (html entities) in the link texts, you have to pass the arguments through an array:

paginate_comments_links( [
	'prev_text' => '«', 
	'next_text' => '»'
] );

Notes

See: paginate_links()
Global. WP_Rewrite. $wp_rewrite WordPress rewrite component.

Changelog

Since 2.7.0

Introduced.

`paginate_comments_links() paginate comments links` code ^{WP 6.9.1}

wp-includes/link-template.php

function paginate_comments_links( $args = array() ) {
	global $wp_rewrite;

	if ( ! is_singular() ) {
		return;
	}

	$page = get_query_var( 'cpage' );
	if ( ! $page ) {
		$page = 1;
	}
	$max_page = get_comment_pages_count();
	$defaults = array(
		'base'         => add_query_arg( 'cpage', '%#%' ),
		'format'       => '',
		'total'        => $max_page,
		'current'      => $page,
		'echo'         => true,
		'type'         => 'plain',
		'add_fragment' => '#comments',
	);
	if ( $wp_rewrite->using_permalinks() ) {
		$defaults['base'] = user_trailingslashit( trailingslashit( get_permalink() ) . $wp_rewrite->comments_pagination_base . '-%#%', 'commentpaged' );
	}

	$args       = wp_parse_args( $args, $defaults );
	$page_links = paginate_links( $args );

	if ( $args['echo'] && 'array' !== $args['type'] ) {
		echo $page_links;
	} else {
		return $page_links;
	}
}