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. Ray Gulick
    Permalink to comment#

    Pasted as is, this breaks my functions file.

  2. eric
    Permalink to comment#

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

    • Tiffany

      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.

    • alkinkasap
      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. MikiaFto5

    Good theory. I like it. Appreciate your posting

  4. Hakan
    Permalink to comment#

    thanks.. very good

  5. 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. Ralph
    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. 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. 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 :)

    • Ven

      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. John
    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. Alex

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

    • 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. 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. 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. sam
    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. sam
    Permalink to comment#

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

  15. Tahmid

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

  16. mrm
    Permalink to comment#

    thanks alot
    that was useful

  17. Randy
    Permalink to comment#

    Thanks sir. Straight to the point. :)

  18. mike
    Permalink to comment#

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

    • 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

We highly encourage you to post problematic HTML/CSS/JavaScript over on CodePen and include the link in your post. It's much easier to see, understand, and help with when you do that.

Markdown is supported, so you can write inline code like `<div>this</div>` or multiline blocks of code in triple backtick fences like this:

  function example() {
    element.innerHTML = "<div>code</div>";

We have a pretty good* newsletter.