Customize Comments Markup

In a typical WordPress theme you output the entire list of comments for a Post/Page by using the function wp_list_comments(). This doesn't offer much by the way of customizing what HTML markup gets generated for that comment list. To write your own markup for the comment list, you can use a callback function as a parameter in wp_list_comments(), so it's just as nicely abstracted.

In functions.php

function my_custom_comments($comment, $args, $depth) {
   $GLOBALS['comment'] = $comment; ?>
   <li <?php comment_class(); ?> id="li-comment-<?php comment_ID() ?>">
   <?php if ($comment->comment_approved == '0') : ?>
      <em><?php _e('Your comment is awaiting moderation.') ?></em>
   <?php endif; ?>

   // Comments markup code here, e.g. functions like comment_text(); 


In comments.php



  1. User Avatar
    Ray Gulick
    Permalink to comment#

    Pasted as is, this breaks my functions file.

  2. User Avatar
    Permalink to comment#

    God, I swear there’s like NOTHING out there that thoroughly explains comments for WP.

    • User Avatar

      I completely agree. I’m building my first theme and I can’t find anything on the web that gives a great “tutorial-like” breakdown of customizing the comments section. SOOOO frustrating.

    • User Avatar
      Permalink to comment#

      God, i couldn’t agree more..

      First time i want to use custom comments made by me and cant find anything anywhere?!

      Why doesnt someone share something really helpful?

  3. User Avatar

    Good theory. I like it. Appreciate your posting

  4. User Avatar
    Permalink to comment#

    thanks.. very good

  5. User Avatar
    Devin Clark
    Permalink to comment#

    The reason is breaks is because the php tag isn’t opened at the end with the closing bracket. It should look like the above code.

  6. User Avatar
    Permalink to comment#

    This was a great help. With basic php knowledge and adding a few php tags your code works a treat. I recommend playing with these functions to get the desired result:

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

  7. User Avatar
    Anna Funk
    Permalink to comment#

    This code is extremely useful if you’re already familiar with PHP, but it’s not complete, and it does break the functions.php file. However, I played around with it and came up with a conversion that can be pasted directly into the functions.php.

    View the code at PasteBin

    It’s tested, but not thoroughly, so use at your own risk. But if you use the list of functions that Ralph posted, you should be able to create your custom comments.

    Make sure to use the same


    that Chris posted in your comments.php file.

  8. User Avatar
    Rowe Morehouse
    Permalink to comment#

    I agree it was difficult to find info on doing custom styling for wordpress comments. Here is the function I finally used — hope this helps! … It allows a lot of customization. I also included a function for changing the default gravatar image if you want to use your own image instead of “mystery man” or the other gravatar defaults. Link to my gist below.

    // Customize Worpress Comments Form Template HTML 
    add_filter('genesis_comment_form_args','custom_comments_function'); /*change the comment_form_args for your theme - this is for genesis, which is a "hooked" theme.*/
    function custom_comments_function() {
    global $current_user;
    $args = array(
            'fields' => array(
                'author' => '<BR />' .
                            '<input id="author" name="author" type="text" class="required" placeholder="Your Name" minlength="2" value="' . esc_attr( $commenter['comment_author'] ) . '" size="30" tabindex="1"' . $aria_req . ' />' .
                            ( $req ? '<span class="required">*</span>' : '' ) .
                'email' =>  '<p class="comment-form-email">' .
                            '<input id="email" name="email" type="text" class="required" placeholder="Your Email" value="' . esc_attr(  $commenter['comment_author_email'] ) . '" size="30" tabindex="2"' . $aria_req . ' />' .
                            '<label for="email">' . __( '<span class="breadcrumb-lead">YOUR EMAIL ADDRESS IS NOT PUBLISHED & REMAINS PRIVATE.</span>', 'genesis' ) . '</label> ' .
                            ( $req ? '<span class="required">*</span>' : '' ) .
                'url' =>    ''
            'comment_field' =>  '<p class="comment-form-comment">' .
                                '<textarea id="comment" name="comment" cols="45" rows="8" tabindex="4" aria-required="true"></textarea>' .
            'title_reply' => __( 'Add a comment, a question:', 'genesis' ), /*change for your theme, and for what you want your comments header to say*/
            'comment_notes_before' => '<small><span class="muted" style="font-style: italic;">All comments are moderated.</span></small>',
            'logged_in_as' => '<p class="logged-in-as">' . sprintf( __( '<small>You are currently logged in as <a href="%1$s">%2$s</a> ... <a href="%3$s" title="Log out of this account">Log out?</a></small>' ), admin_url( 'profile.php' ), $current_user->user_login, wp_logout_url( apply_filters( 'the_permalink', get_permalink( ) ) ) ) . '</p>',
            'label_submit' => __( ' Don\'t Be Shy, Submit Your Comment Now! ' ),
            'class_submit' => __( 'btn btn-info' ), /*As far as I've found, you can't style the button without changing a core file (or using a plugin) which kinda sucks, but this is where you would express the button styling*/
            'comment_notes_after' => '',
        return $args;
    // Change default comments gravatar to a custom image
    add_filter( 'avatar_defaults', 'newgravatar' );  
    function newgravatar ($avatar_defaults) {  
        $myavatarPurple = get_bloginfo('template_directory') . '/images/purple_user_avatar.png'; /* use ftp to upload your custom avatar to the images dir */ 
        $avatar_defaults[$myavatarPurple] = "Purple User Avatar"; 
        /* now choose your new default avatar win wordpress > setttings > discussion */

    Here’s the gist, if you wanna download the file :)

    • User Avatar

      I would be very interested to learn from this, are you planning to do a tutorial regarding this snippet? thank you in advance if so :)

  9. User Avatar
    Permalink to comment#

    Thanks a lot Rowe for your much appreciated snippet of php code. This is definetley the kind of extra that adds value to one’s WordPress website, let alone CSS tips and tricks ;-)

  10. User Avatar

    I think you forgot to add the closing ” tag before closing the function.

    • User Avatar
      Chris Coyier

      Looks like your HTML got gobbled up there, but if you meant <li> tag, you are specifically supposed to leave that off. WordPress will close them as needed. It needs you to do that for threading comments.

  11. User Avatar
    Eric Scism
    Permalink to comment#

    Thanks for this Chris. I’ve been reading for a long time. Personally I’m not too concerned about the comments section of my site. I just use Disqus and love it. Super simple to manage. Not much customization though which is fine with me. However sometimes my clients want more customization and that’s where this can come in real handy. So thanks again!

  12. User Avatar
    Chris Ferdinandi
    Permalink to comment#

    I know this is an old post, but I’m still not sure I get why hiding the comment output behind a callback in wp_list_comments() is better than the old way, where all of the markup was obvious and included in the comments.php file.

  13. User Avatar
    Permalink to comment#

    How can I have a comment box like this on my wordpress site? However, the bold or italic part does not see to work!

  14. User Avatar
    Permalink to comment#

    Sorry I take it does work..Would love to have this comment box on my website

  15. User Avatar

    Thanks for sharing. But I am searching for CSS of the Comment template.

  16. User Avatar
    Permalink to comment#

    thanks alot
    that was useful

  17. User Avatar
    Permalink to comment#

    Thanks sir. Straight to the point. :)

  18. User Avatar
    Permalink to comment#

    just noticed that the callback code in your snippet is a bit wrong chris – should be

    • User Avatar
      Chris Coyier
      Permalink to comment#

      Did that API change? Different best practice?

      What’s in use literally on this comment thread right now we’re looking at is:

      <?php wp_list_comments('type=comment&avatar_size=512&callback=csstricks_comment'); ?>

Leave a Comment

Posting Code!

You may write comments in Markdown. This makes code easy to post, as you can write inline code like `<div>this</div>` or multiline blocks of code in triple backtick fences (```) with double new lines before and after.

Code of Conduct

Absolutely anyone is welcome to submit a comment here. But not all comments will be posted. Think of it like writing a letter to the editor. All submitted comments will be read, but not all published. Published comments will be on-topic, helpful, and further the discussion or debate.

Want to tell us something privately?

Feel free to use our contact form. That's a great place to let us know about typos or anything off-topic.