WordPress.org

Languages: English • 日本語 한국어 • (Add your language)

Description

Displays all comments for a post or Page based on a variety of parameters including ones set in the administration area.

See also: Migrating Plugins and Themes to 2.7

Usage

 <?php wp_list_comments( $args, $comments ); ?> 

Default Usage

$args

(array) (optional) The options for the function.

Default:

<?php $args = array(
	'walker'            => null,
	'max_depth'         => '',
	'style'             => 'ul',
	'callback'          => null,
	'end-callback'      => null,
	'type'              => 'all',
	'reply_text'        => 'Reply',
	'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.

$comments

(array) (optional) Array obtained by get_comments query.

Default: The default return of get_comments.

Arguments

'walker' 

( Walker object ) Provide a custom Walker class object to use when rendering the comments. This is the primary method of customizing comment HTML.

<?php
wp_list_comments( array(
    'walker' => new Walker_Comment()
) );

'max_depth' 

( integer ) How deep (in comment replies) should the comments be fetched.

'style' 

( string ) Can be either 'div', 'ol', or 'ul' (the default). Note that any containing tags that must be written explicitly. For instance:

<div class="comment list">
    <?php wp_list_comments( array( 'style' => 'div' ) ); ?>
</div>

OR

<ol class="comment list">
    <?php wp_list_comments( array( 'style' => 'ol' ) ); ?>
</ol>

'callback' 

( callback ) The name of a custom function to use to open and display each comment. Using this will make your custom function get called to display each comment, bypassing all internal WordPress functionality in this respect. Use to customize comments display for extreme changes to the HTML layout. Note that your callback must include the opening <div>, <ol>, or <ul> tag (corresponding with the style parameter), but not the closing tags. WordPress will supply the closing tag automatically, or you can use end-callback to override this default. The callback is separate from the end-callback to facilitate hierarchical comments. Use with caution.

'end-callback' 

( callback ) The name of a custom function to use to close each comment. Using this will make your custom function get called to at the end of each comment, bypassing the WordPress default of using </div>, </ol>, or </li> based on the style parameter. Use to customize the ending tags for a comment. The callback is separate from the end-callback to facilitate hierarchical comments. Use with caution.

'type' 

( string ) The type of comment(s) to display. Can be 'all', 'comment', 'trackback', 'pingback', or 'pings'. 'pings' is both 'trackback' and 'pingback' together.

'reply_text' 

( string ) Text to display in each comment as a reply link. (This isn't an argument of this function but it gets passed to the get_comment_reply_link function.)

'page' 

( integer ) The current page in the pagination to display.

'per_page' 

( integer ) The number of items to show for each page of comments.

'avatar_size' 

( integer ) Size that the avatar should be shown as, in pixels. http://gravatar.com/ supports sizes between 1 and 512. Use 0 to hide avatars.

'reverse_top_level' 

( boolean ) Setting this to true will display the most recent comment first then going back in order, and setting this to false will show the oldest comments first. If not specified, it will use the value stored in the WordPress dashboard settings.

'reverse_children' 

( boolean ) Setting this to true will display the children (reply level comments) with the most recent ones first, then going back in order.

'format' 

( boolean ) This can be set to 'html5' or 'xhtml' - it defaults to your theme's current_theme_supports( 'html5' ) setting.

'short_ping' 

( boolean ) Whether you want to use a short ping.

'echo' 

( boolean ) Whether to echo the list or just return it.

Examples

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.

<ol class="commentlist">
<?php wp_list_comments(); ?>
</ol>

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.

<ul class="commentlist">
<?php wp_list_comments( 'type=comment&callback=mytheme_comment' ); ?>
</ul>

You will need to define your custom callback function in your theme's functions.php file. Here is an example:

function mytheme_comment($comment, $args, $depth) {
    if ( 'div' === $args['style'] ) {
        $tag       = 'div';
        $add_below = 'comment';
    } else {
        $tag       = 'li';
        $add_below = 'div-comment';
    }?>
    <<?php echo $tag; ?> <?php comment_class( empty( $args['has_children'] ) ? '' : 'parent' ); ?> id="comment-<?php comment_ID() ?>"><?php 
    if ( 'div' != $args['style'] ) { ?>
        <div id="div-comment-<?php comment_ID() ?>" class="comment-body"><?php
    } ?>
        <div class="comment-author vcard"><?php 
            if ( $args['avatar_size'] != 0 ) {
                echo get_avatar( $comment, $args['avatar_size'] ); 
            } 
            printf( __( '<cite class="fn">%s</cite> <span class="says">says:</span>' ), get_comment_author_link() ); ?>
        </div><?php 
        if ( $comment->comment_approved == '0' ) { ?>
            <em class="comment-awaiting-moderation"><?php _e( 'Your comment is awaiting moderation.' ); ?></em><br/><?php 
        } ?>
        <div class="comment-meta commentmetadata">
            <a href="<?php echo htmlspecialchars( get_comment_link( $comment->comment_ID ) ); ?>"><?php
                /* translators: 1: date, 2: time */
                printf( 
                    __('%1$s at %2$s'), 
                    get_comment_date(),  
                    get_comment_time() 
                ); ?>
            </a><?php 
            edit_comment_link( __( '(Edit)' ), '  ', '' ); ?>
        </div>

        <?php comment_text(); ?>

        <div class="reply"><?php 
                comment_reply_link( 
                    array_merge( 
                        $args, 
                        array( 
                            'add_below' => $add_below, 
                            'depth'     => $depth, 
                            'max_depth' => $args['max_depth'] 
                        ) 
                    ) 
                ); ?>
        </div><?php 
    if ( 'div' != $args['style'] ) : ?>
        </div><?php 
    endif;
}

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.

Display Comments for a Specific Page/Post

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.

<ol class="commentlist">
	<?php
		//Gather comments for a specific page/post 
		$comments = get_comments(array(
			'post_id' => XXX,
			'status' => 'approve' //Change this to the type of comments to be displayed
		));

		//Display the list of comments
		wp_list_comments(array(
			'per_page' => 10, //Allow comment pagination
			'reverse_top_level' => false //Show the oldest comments at the top of the list
		), $comments);
	?>
</ol>

Change Log

Since: 2.7.0

Source File

wp_list_comments() is located in wp-includes/comment-template.php.

Related

Comments Functions

• Function: cancel_comment_reply_link()
• Function: comment_author()
• Function: comment_author_email()
• Function: comment_author_email_link()
• Function: comment_author_IP()
• Function: comment_author_link()
• Function: comment_author_rss()
• Function: comment_author_url()
• Function: comment_author_url_link()
• Function: comment_class()
• Function: comment_date()
• Function: comment_excerpt()
• Function: comment_form_title()
• Function: comment_form(),
• Function: comment_ID()
• Function: comment_id_fields()
• Function: comment_reply_link()
• Function: comment_text()
• Function: comment_text_rss()
• Function: comment_time()
• Function: comment_type()
• Function: comments_link
• Function: comments_number()
• Function: comments_open(),
• Function: comments_popup_link()
• Function: comments_popup_script()
• Function: comments_rss_link()
• Function: get_avatar()
• Function: next_comments_link()
• Function: paginate_comments_links()
• Function: permalink_comments_rss()
• Function: previous_comments_link()
• Function: wp_list_comments()

List & Dropdown Functions

• Function: wp_list_authors()
• Function: wp_list_categories()
• Function: wp_list_pages()
• Function: wp_list_bookmarks()
• Function: wp_list_comments()
• Function: wp_get_archives()
• Function: wp_page_menu()
• Function: wp_dropdown_pages()
• Function: wp_dropdown_categories()
• Function: wp_dropdown_users()
• Function: wp_dropdown_roles()
• Function: wp_dropdown_languages()