wp_list_comments( string|array $args = array(), WP_Comment[] $comments = null )
Displays a list of comments.
Contents
Description Description
Used in the comments.php template to list comments for a particular post.
See also See also
- WP_Query->comments
Parameters Parameters
- $args
-
(string|array) (Optional) Formatting options.
- 'walker'
(object) Instance of a Walker class to list comments. Default null. - 'max_depth'
(int) The maximum comments depth. - 'style'
(string) The style of list ordering. Accepts 'ul', 'ol', or 'div'. 'div' will result in no additional list markup. Default 'ul'. - 'callback'
(callable) Callback function to use. Default null. - 'end-callback'
(callable) Callback function to use at the end. Default null. - 'type'
(string) Type of comments to list. Accepts 'all', 'comment', 'pingback', 'trackback', 'pings'. Default 'all'. - 'page'
(int) Page ID to list comments for. - 'per_page'
(int) Number of comments to list per page. - 'avatar_size'
(int) Height and width dimensions of the avatar size. Default 32. - 'reverse_top_level'
(bool) Ordering of the listed comments. If true, will display newest comments first. Default null. - 'reverse_children'
(bool) Whether to reverse child comments in the list. Default null. - 'format'
(string) How to format the comments list. Accepts 'html5', 'xhtml'. Default 'html5' if the theme supports it. - 'short_ping'
(bool) Whether to output short pings. Default false. - 'echo'
(bool) Whether to echo the output or return it. Default true.
Default value: array()
- 'walker'
- $comments
-
(WP_Comment[]) (Optional) Array of WP_Comment objects.
Default value: null
Return Return
(void|string) Void if 'echo' argument is true, or no comments to list. Otherwise, HTML list of comments.
More Information More Information
Default options for $args
$args = array( 'walker' => null, 'max_depth' => '', 'style' => 'ul', 'callback' => null, 'end-callback' => null, 'type' => 'all', 'page' => '', 'per_page' => '', 'avatar_size' => 32, 'reverse_top_level' => null, 'reverse_children' => '', 'format' => 'html5', // or 'xhtml' if no 'HTML5' theme support 'short_ping' => false, // @since 3.6 'echo' => true // boolean, default is true );
The ‘max_depth
‘, ‘per_page
‘, and ‘reverse_top_level
‘ parameters can be more easily controlled through the Discussion Settings Administration Panel but a theme can override those settings.
Source Source
File: wp-includes/comment-template.php
function wp_list_comments( $args = array(), $comments = null ) { global $wp_query, $comment_alt, $comment_depth, $comment_thread_alt, $overridden_cpage, $in_comment_loop; $in_comment_loop = true; $comment_alt = 0; $comment_thread_alt = 0; $comment_depth = 1; $defaults = array( 'walker' => null, 'max_depth' => '', 'style' => 'ul', 'callback' => null, 'end-callback' => null, 'type' => 'all', 'page' => '', 'per_page' => '', 'avatar_size' => 32, 'reverse_top_level' => null, 'reverse_children' => '', 'format' => current_theme_supports( 'html5', 'comment-list' ) ? 'html5' : 'xhtml', 'short_ping' => false, 'echo' => true, ); $parsed_args = wp_parse_args( $args, $defaults ); /** * Filters the arguments used in retrieving the comment list. * * @since 4.0.0 * * @see wp_list_comments() * * @param array $parsed_args An array of arguments for displaying comments. */ $parsed_args = apply_filters( 'wp_list_comments_args', $parsed_args ); // Figure out what comments we'll be looping through ($_comments). if ( null !== $comments ) { $comments = (array) $comments; if ( empty( $comments ) ) { return; } if ( 'all' !== $parsed_args['type'] ) { $comments_by_type = separate_comments( $comments ); if ( empty( $comments_by_type[ $parsed_args['type'] ] ) ) { return; } $_comments = $comments_by_type[ $parsed_args['type'] ]; } else { $_comments = $comments; } } else { /* * If 'page' or 'per_page' has been passed, and does not match what's in $wp_query, * perform a separate comment query and allow Walker_Comment to paginate. */ if ( $parsed_args['page'] || $parsed_args['per_page'] ) { $current_cpage = get_query_var( 'cpage' ); if ( ! $current_cpage ) { $current_cpage = 'newest' === get_option( 'default_comments_page' ) ? 1 : $wp_query->max_num_comment_pages; } $current_per_page = get_query_var( 'comments_per_page' ); if ( $parsed_args['page'] != $current_cpage || $parsed_args['per_page'] != $current_per_page ) { $comment_args = array( 'post_id' => get_the_ID(), 'orderby' => 'comment_date_gmt', 'order' => 'ASC', 'status' => 'approve', ); if ( is_user_logged_in() ) { $comment_args['include_unapproved'] = array( get_current_user_id() ); } else { $unapproved_email = wp_get_unapproved_comment_author_email(); if ( $unapproved_email ) { $comment_args['include_unapproved'] = array( $unapproved_email ); } } $comments = get_comments( $comment_args ); if ( 'all' !== $parsed_args['type'] ) { $comments_by_type = separate_comments( $comments ); if ( empty( $comments_by_type[ $parsed_args['type'] ] ) ) { return; } $_comments = $comments_by_type[ $parsed_args['type'] ]; } else { $_comments = $comments; } } // Otherwise, fall back on the comments from `$wp_query->comments`. } else { if ( empty( $wp_query->comments ) ) { return; } if ( 'all' !== $parsed_args['type'] ) { if ( empty( $wp_query->comments_by_type ) ) { $wp_query->comments_by_type = separate_comments( $wp_query->comments ); } if ( empty( $wp_query->comments_by_type[ $parsed_args['type'] ] ) ) { return; } $_comments = $wp_query->comments_by_type[ $parsed_args['type'] ]; } else { $_comments = $wp_query->comments; } if ( $wp_query->max_num_comment_pages ) { $default_comments_page = get_option( 'default_comments_page' ); $cpage = get_query_var( 'cpage' ); if ( 'newest' === $default_comments_page ) { $parsed_args['cpage'] = $cpage; /* * When first page shows oldest comments, post permalink is the same as * the comment permalink. */ } elseif ( 1 == $cpage ) { $parsed_args['cpage'] = ''; } else { $parsed_args['cpage'] = $cpage; } $parsed_args['page'] = 0; $parsed_args['per_page'] = 0; } } } if ( '' === $parsed_args['per_page'] && get_option( 'page_comments' ) ) { $parsed_args['per_page'] = get_query_var( 'comments_per_page' ); } if ( empty( $parsed_args['per_page'] ) ) { $parsed_args['per_page'] = 0; $parsed_args['page'] = 0; } if ( '' === $parsed_args['max_depth'] ) { if ( get_option( 'thread_comments' ) ) { $parsed_args['max_depth'] = get_option( 'thread_comments_depth' ); } else { $parsed_args['max_depth'] = -1; } } if ( '' === $parsed_args['page'] ) { if ( empty( $overridden_cpage ) ) { $parsed_args['page'] = get_query_var( 'cpage' ); } else { $threaded = ( -1 != $parsed_args['max_depth'] ); $parsed_args['page'] = ( 'newest' === get_option( 'default_comments_page' ) ) ? get_comment_pages_count( $_comments, $parsed_args['per_page'], $threaded ) : 1; set_query_var( 'cpage', $parsed_args['page'] ); } } // Validation check. $parsed_args['page'] = (int) $parsed_args['page']; if ( 0 == $parsed_args['page'] && 0 != $parsed_args['per_page'] ) { $parsed_args['page'] = 1; } if ( null === $parsed_args['reverse_top_level'] ) { $parsed_args['reverse_top_level'] = ( 'desc' === get_option( 'comment_order' ) ); } wp_queue_comments_for_comment_meta_lazyload( $_comments ); if ( empty( $parsed_args['walker'] ) ) { $walker = new Walker_Comment; } else { $walker = $parsed_args['walker']; } $output = $walker->paged_walk( $_comments, $parsed_args['max_depth'], $parsed_args['page'], $parsed_args['per_page'], $parsed_args ); $in_comment_loop = false; if ( $parsed_args['echo'] ) { echo $output; } else { return $output; } }
Expand full source code Collapse full source code View on Trac
Changelog Changelog
Version | Description |
---|---|
2.7.0 | Introduced. |
User Contributed Notes User Contributed Notes
You must log in before being able to contribute a note or feedback.
Example migrated from Codex:
Comments Only With A Custom Comment Display
Displays just comments (no pingbacks or trackbacks) while using a custom callback function to control the look of the comment. You may want to add a
max_depth=X
parameter, if the reply links are not appearing.You will need to define your custom callback function in your theme’s functions.php file. Here is an example:
Expand full source codeCollapse full source code
Note the lack of a trailing
</li>
. In order to accommodate nested replies, WordPress will add the appropriate closing tag after listing any child elements.If you are using WordPress 4.9.6 or higher and not showing “Comment is awaiting moderation” alert.
You can follow the steps below.
– ) Settings -> Discussion -> enable “Show comments cookies opt-in checkbox.”
– ) After activating checkbox will show on comments form like this. “Save my name, email, and website in this browser for the next time I comment.”
That’s it.
If you want to customize this checkbox field, you can use this code.
wp_list_comments()
will not do anything by itself. It has to be called from inside thecomments template
file.An example:
The page/post file where you want to insert comments:
Then, in
comments.php
:Customize the default wp_list_comments();
Example migrated from Codex:
Default Usage
Outputs an ordered list of the comments. Things like threading or paging being enabled or disabled are controlled via the Settings Discussion SubPanel.
Example migrated from Codex:
Outputs an ordered list of comments for a specific page or post. Things like threading or paging being enabled or disabled are controlled via the Settings Discussion SubPanel.
Expand full source codeCollapse full source code