Paginating comment links in WordPress with paginate_comments_links

The paginate_comments_links function in WordPress is designed to handle the output of comment pagination links. This function is part of the WordPress core and is typically used when a website has a large number of comments and wants to split them into multiple pages.

When called, the paginate_comments_links function automatically generates the correct pagination links based on the current page and the total number of comment pages. The generated links can be used to navigate between different pages of comments. The function will display the links in the place where it is called, typically within a theme file.

It is important to note that the paginate_comments_links function will only generate and display the pagination links. It does not handle the actual splitting of comments into different pages or the displaying of comments on each page. Other functions within WordPress are responsible for this functionality.

By using the paginate_comments_links function, developers can ensure a consistent and standard way of displaying comment pagination links across different themes and plugins. This can also help to maintain a consistent user experience across different parts of a website.

Parameters of the paginate_comments_links Function

The paginate_comments_links function in WordPress is designed to accept one parameter:

  • $args (string|array) – This is an optional parameter. The default value is an empty array. It is utilized for optional arguments, the specifics of which can be found in the paginate_links() function.

Return Value of the paginate_comments_links Function

The return value of the paginate_comments_links function varies depending on certain conditions:

If the ‘echo’ argument is set to true and ‘type’ is not an array, or if the query does not correspond to an existing single post of any post type, the function will return void. Otherwise, the function will return either the markup for comment page links or an array of comment page links, depending on the ‘type’ argument.


Example 1: Basic Usage of paginate_comments_links

if ( get_comment_pages_count() > 1 && get_option( 'page_comments' ) ) : 
 echo '<div class="comment-navigation">';
 echo '</div>';

In this example, we first check if there is more than one page of comments and if the ‘page_comments’ option is enabled in the WordPress settings. If both conditions are met, we display the comment pagination links wrapped in a div with the class ‘comment-navigation’. The paginate_comments_links() function is used without any arguments, so it uses the default settings.

Example 2: Using the ‘prev_text’ and ‘next_text’ parameters

$args = array(
 'prev_text' => __('« Older Comments'),
 'next_text' => __('Newer Comments »'),

In this example, we are passing an array to the paginate_comments_links() function to customize the text for the previous and next links. The ‘prev_text’ parameter changes the text for the link to the older comments, and the ‘next_text’ parameter changes the text for the link to the newer comments.

Example 3: Using the ‘type’ parameter

$args = array(
 'type' => 'array',
$links = paginate_comments_links($args);
if($links) {
 echo '<ul class="pagination">';
 foreach ($links as $link) {
 echo '<li>' . $link . '</li>';
 echo '</ul>';

In this example, we set the ‘type’ parameter to ‘array’. This causes the paginate_comments_links() function to return an array of links rather than a string of HTML. We then loop through the array and output each link as an item in an unordered list. This gives us more control over the HTML structure of the pagination links.


The paginate_comments_links function in WordPress is a tool that generates pagination links for comment pages. This function can be especially useful when dealing with posts that have a large number of comments, as it allows for easier navigation and a more organized structure. By utilizing the paginate_comments_links function, developers can improve the user experience on their WordPress sites by making comment sections more manageable and user-friendly.

Related WordPress Functions