The WordPress Theme Comments Template

Update: We’ve created a second edition of this article, with updated code samples and coverage of the latest theme development techniques. Check it out at The WordPress Theme Comments Template. It’s part of The ThemeShaper WordPress Theme Tutorial: 2nd Edition.

I hate the Comments Template. There, I said it. It can be a confusing mess. In version 2.7, WordPress introduced a simpler way of producing Comments Templates—which was no help if you wanted to separate your comments and trackbacks or have custom comment markup. It’s still confusing.

Luckily for you, I’ve sorted it out. Confusing still, yes. But sorted out. For this tutorial on the Comments Template I’m basically going to walk you through what’s going to happen, show you some custom code snippets you’ll need to add to your functions.php, and then drop the whole thing on you. Hopefully, it’ll start to make sense. But at they very least you’ll have a wicked comments template.

Let’s take a look at a quick list of what’s going on in this Template.

  1. Prevent loading for bots and on password protected posts
  2. Check if there are comments
  3. Count the number of comments and trackbacks (or pings)
  4. If there are comments, show the comments—with navigation for paginated comments
  5. If there are trackbacks, show the trackbacks
  6. If comments are open, show the comments “respond” form

That’s a lot of stuff going on for one template. But written out like that, it’s pretty straightforward.

Custom Callbacks for Comments and Trackbacks

Now, with WordPress 2.7 came the function wp_list_comments() that conveniently spits out an ordered list of comments and trackbacks markup for your post (threaded too). Convenient if you want that. And we don’t. We want separated threaded comments and trackbacks, with our own custom markup.

To make the comments template code I’m going to give you work, you’ll need a set of custom callbacks for your list of Comments and Trackbacks. Add the following 2 functions to your theme functions.php file.

// Custom callback to list comments in the your-theme style
function custom_comments($comment, $args, $depth) {
  $GLOBALS['comment'] = $comment;
	$GLOBALS['comment_depth'] = $depth;
  	<li id="comment-<?php comment_ID() ?>" <?php comment_class() ?>>
  		<div class="comment-author vcard"><?php commenter_link() ?></div>
  		<div class="comment-meta"><?php printf(__('Posted %1$s at %2$s <span class="meta-sep">|</span> <a href="%3$s" title="Permalink to this comment">Permalink</a>', 'your-theme'),
  					'#comment-' . get_comment_ID() );
  					edit_comment_link(__('Edit', 'your-theme'), ' <span class="meta-sep">|</span> <span class="edit-link">', '</span>'); ?></div>
  <?php if ($comment->comment_approved == '0') _e("ttttt<span class='unapproved'>Your comment is awaiting moderation.</span>n", 'your-theme') ?>
          <div class="comment-content">
      		<?php comment_text() ?>
		<?php // echo the comment reply link
			if($args['type'] == 'all' || get_comment_type() == 'comment') :
				comment_reply_link(array_merge($args, array(
					'reply_text' => __('Reply','your-theme'),
					'login_text' => __('Log in to reply.','your-theme'),
					'depth' => $depth,
					'before' => '<div class="comment-reply-link">',
					'after' => '</div>'
<?php } // end custom_comments
// Custom callback to list pings
function custom_pings($comment, $args, $depth) {
       $GLOBALS['comment'] = $comment;
    		<li id="comment-<?php comment_ID() ?>" <?php comment_class() ?>>
    			<div class="comment-author"><?php printf(__('By %1$s on %2$s at %3$s', 'your-theme'),
    					get_comment_time() );
    					edit_comment_link(__('Edit', 'your-theme'), ' <span class="meta-sep">|</span> <span class="edit-link">', '</span>'); ?></div>
    <?php if ($comment->comment_approved == '0') _e('ttttt<span class="unapproved">Your trackback is awaiting moderation.</span>n', 'your-theme') ?>
            <div class="comment-content">
    			<?php comment_text() ?>
<?php } // end custom_pings

Those look kind of hairy don’t they? But you’re better off for it. Now you have access to the comments markup. I think the markup I’ve got in there is pretty sweet and will let you make a lot of changes with just CSS alone, but if you do want to alter the markup, well, there it is.

We’ll also need a special custom function that the custom_comments() is calling. This function will markup the gravatar we’re using so it fits into the microformat schema for hcard.

// Produces an avatar image with the hCard-compliant photo class
function commenter_link() {
	$commenter = get_comment_author_link();
	if ( ereg( '<a[^>]* class=[^>]+>', $commenter ) ) {
		$commenter = ereg_replace( '(<a[^>]* class=['"]?)', '\1url ' , $commenter );
	} else {
		$commenter = ereg_replace( '(<a )/', '\1class="url "' , $commenter );
	$avatar_email = get_comment_author_email();
	$avatar = str_replace( "class='avatar", "class='photo avatar", get_avatar( $avatar_email, 80 ) );
	echo $avatar . ' <span class="fn n">' . $commenter . '</span>';
} // end commenter_link

If you want to change the default size of your gravatar just change the 80 in get_avatar( $avatar_email, 80 ) ). The 80 is the size in pixels of your gravatar.

The Comments Template

I haven’t scared you away have I? I’ll be honest, it’s not that scary. Here’s the comments template with some helpful PHP comments that should guide you along in understanding what’s happening.

<?php /* The Comments Template — with, er, comments! */ ?>
			<div id="comments">
<?php /* Run some checks for bots and password protected posts */ ?>
	$req = get_option('require_name_email'); // Checks if fields are required.
	if ( 'comments.php' == basename($_SERVER['SCRIPT_FILENAME']) )
		die ( 'Please do not load this page directly. Thanks!' );
	if ( ! empty($post->post_password) ) :
		if ( $_COOKIE['wp-postpass_' . COOKIEHASH] != $post->post_password ) :
				<div class="nopassword"><?php _e('This post is password protected. Enter the password to view any comments.', 'your-theme') ?></div>
			</div><!-- .comments -->

<?php /* See IF there are comments and do the comments stuff! */ ?>
<?php if ( have_comments() ) : ?>

<?php /* Count the number of comments and trackbacks (or pings) */
$ping_count = $comment_count = 0;
foreach ( $comments as $comment )
	get_comment_type() == "comment" ? ++$comment_count : ++$ping_count;

<?php /* IF there are comments, show the comments */ ?>
<?php if ( ! empty($comments_by_type['comment']) ) : ?>

				<div id="comments-list" class="comments">
					<h3><?php printf($comment_count > 1 ? __('<span>%d</span> Comments', 'your-theme') : __('<span>One</span> Comment', 'your-theme'), $comment_count) ?></h3>

<?php /* If there are enough comments, build the comment navigation  */ ?>
<?php $total_pages = get_comment_pages_count(); if ( $total_pages > 1 ) : ?>
					<div id="comments-nav-above" class="comments-navigation">
								<div class="paginated-comments-links"><?php paginate_comments_links(); ?></div>
					</div><!-- #comments-nav-above -->
<?php endif; ?>

<?php /* An ordered list of our custom comments callback, custom_comments(), in functions.php   */ ?>
<?php wp_list_comments('type=comment&amp;callback=custom_comments'); ?>

<?php /* If there are enough comments, build the comment navigation */ ?>
<?php $total_pages = get_comment_pages_count(); if ( $total_pages > 1 ) : ?>
	  			<div id="comments-nav-below" class="comments-navigation">
						<div class="paginated-comments-links"><?php paginate_comments_links(); ?></div>
	        </div><!-- #comments-nav-below -->
<?php endif; ?>

				</div><!-- #comments-list .comments -->

<?php endif; /* if ( $comment_count ) */ ?>

<?php /* If there are trackbacks(pings), show the trackbacks  */ ?>
<?php if ( ! empty($comments_by_type['pings']) ) : ?>

				<div id="trackbacks-list" class="comments">
					<h3><?php printf($ping_count > 1 ? __('<span>%d</span> Trackbacks', 'your-theme') : __('<span>One</span> Trackback', 'your-theme'), $ping_count) ?></h3>

<?php /* An ordered list of our custom trackbacks callback, custom_pings(), in functions.php   */ ?>
<?php wp_list_comments('type=pings&amp;callback=custom_pings'); ?>

				</div><!-- #trackbacks-list .comments -->

<?php endif /* if ( $ping_count ) */ ?>
<?php endif /* if ( $comments ) */ ?>

<?php /* If comments are open, build the respond form */ ?>
<?php if ( 'open' == $post->comment_status ) : ?>
				<div id="respond">
    				<h3><?php comment_form_title( __('Post a Comment', 'your-theme'), __('Post a Reply to %s', 'your-theme') ); ?></h3>

    				<div id="cancel-comment-reply"><?php cancel_comment_reply_link() ?></div>

<?php if ( get_option('comment_registration') &amp;&amp; !$user_ID ) : ?>
					<p id="login-req"><?php printf(__('You must be <a href="%s" title="Log in">logged in</a> to post a comment.', 'your-theme'),
					get_option('siteurl') . '/wp-login.php?redirect_to=' . get_permalink() ) ?></p>

<?php else : ?>
					<div class="formcontainer">

						<form id="commentform" action="<?php echo get_option('siteurl'); ?>/wp-comments-post.php" method="post">

<?php if ( $user_ID ) : ?>
							<p id="login"><?php printf(__('<span class="loggedin">Logged in as <a href="%1$s" title="Logged in as %2$s">%2$s</a>.</span> <span class="logout"><a href="%3$s" title="Log out of this account">Log out?</a></span>', 'your-theme'),
								get_option('siteurl') . '/wp-admin/profile.php',
								wp_specialchars($user_identity, true),
								wp_logout_url(get_permalink()) ) ?></p>

<?php else : ?>

							<p id="comment-notes"><?php _e('Your email is <em>never</em> published nor shared.', 'your-theme') ?> <?php if ($req) _e('Required fields are marked <span class="required">*</span>', 'your-theme') ?></p>

              <div id="form-section-author" class="form-section">
								<div class="form-label"><label for="author"><?php _e('Name', 'your-theme') ?></label> <?php if ($req) _e('<span class="required">*</span>', 'your-theme') ?></div>
								<div class="form-input"><input id="author" name="author" type="text" value="<?php echo $comment_author ?>" size="30" maxlength="20" tabindex="3" /></div>
              </div><!-- #form-section-author .form-section -->

              <div id="form-section-email" class="form-section">
								<div class="form-label"><label for="email"><?php _e('Email', 'your-theme') ?></label> <?php if ($req) _e('<span class="required">*</span>', 'your-theme') ?></div>
								<div class="form-input"><input id="email" name="email" type="text" value="<?php echo $comment_author_email ?>" size="30" maxlength="50" tabindex="4" /></div>
              </div><!-- #form-section-email .form-section -->

              <div id="form-section-url" class="form-section">
								<div class="form-label"><label for="url"><?php _e('Website', 'your-theme') ?></label></div>
								<div class="form-input"><input id="url" name="url" type="text" value="<?php echo $comment_author_url ?>" size="30" maxlength="50" tabindex="5" /></div>
              </div><!-- #form-section-url .form-section -->

<?php endif /* if ( $user_ID ) */ ?>

              <div id="form-section-comment" class="form-section">
								<div class="form-label"><label for="comment"><?php _e('Comment', 'your-theme') ?></label></div>
								<div class="form-textarea"><textarea id="comment" name="comment" cols="45" rows="8" tabindex="6"></textarea></div>
              </div><!-- #form-section-comment .form-section -->

              <div id="form-allowed-tags" class="form-section">
	              <p><span><?php _e('You may use these <abbr title="HyperText Markup Language">HTML</abbr> tags and attributes:', 'your-theme') ?></span> <code><?php echo allowed_tags(); ?></code></p>

<?php do_action('comment_form', $post->ID); ?>

							<div class="form-submit"><input id="submit" name="submit" type="submit" value="<?php _e('Post Comment', 'your-theme') ?>" tabindex="7" /><input type="hidden" name="comment_post_ID" value="<?php echo $id; ?>" /></div>

<?php comment_id_fields(); ?>

<?php /* Just … end everything. We're done here. Close it up. */ ?>

						</form><!-- #commentform -->
					</div><!-- .formcontainer -->
<?php endif /* if ( get_option('comment_registration') &amp;&amp; !$user_ID ) */ ?>
				</div><!-- #respond -->
<?php endif /* if ( 'open' == $post->comment_status ) */ ?>
			</div><!-- #comments -->

And that’s it. You’ve got a pretty sweet custom Comments Template to call your very own.

How To Create a WordPress Theme

This post is part of a WordPress Themes Tutorial that will show you how to create a powerful WordPress Theme from scratch. Read it from the beginning and code yourself up something awesome.

  1. WordPress Theme Tutorial Introduction
  2. Theme Development Tools
  3. Creating a Theme HTML Structure
  4. Template and Directory Structure
  5. The Header Template
  6. The Index Template
  7. The Single Post, Post Attachment, & 404 Templates
  8. The Comments Template
  9. The Search Template & The Page Template
  10. The Archive, Author, Category & Tags Template
  11. The Sidebar Template
  12. Reset-Rebuild Theme CSS & Define Your Layouts

64 thoughts on “The WordPress Theme Comments Template”

  1. These posts keep getting better and better Ian! The comments template has always been a pain to configure. It still is, but I definitely have a better grasp on things after sifting through those PHP comments. This is an excellent resource!

  2. Great post again.

    Could you please share the entire theme with us? I’d like to see how it all goes in a full installation.

    1. i’m with tolmar. it’d be awesome if we could have the theme for download so that we can compare what we’re doing with the finished product to make sure we haven’t screwed up.

      loving this series. i’ll share my personal results when i’m done building mine…. following your articles step by step 😉

      Jon Broom

      1. Hi Ian,

        I’m looking at the comments.php code and I’m not sure but I think there’s some incorrect nesting here:

        Shouldn’t the above be right before ?

  3. I don’t know if this has been asked before, but I have a question about this ‘your-theme’ parameter
    Each time I create a new theme based on this one,do I need to rename this parameter to reflect the new theme name?


  4. Great series. A bit out of my league, but I’m learning stuff each step of the way. Can’t wait to get to css…

    1. i tried it today but i have problems with the comments template et the functions’ one.

      i can’t see the comments proper on the comments page and it seem i miss a closure “?>” somewhere on the functions template.

  5. Think I found an error in your code. In the very first function up top on line six you have:

    but it really should just be

    because it already prints the class=”….”.

  6. Ok, you’re comments don’t like code inputs, lets try it as HTML entities:

    Think I found an error in your code. In the very first function up top on line six you have:
    <code>class="<?php comment_class();?>"</code>

    but it really should just be
    <code><?php comment_class(); ?></code>
    because it already prints the class="….".

  7. Just a quick question, how do I add highlight to author comments? I know that in wp 2.7 it can be done with CSS only. but it doesn’t work with the theme here.

    1. Ian,

      You’ve got a small bug on the comments function in functions.php in the shape theme. in the comment class you should omit the “” and leave the wp_comment_class without “.

      It works great on the function.php in the SVN.

  8. Hi Ian,

    Amazing tutorials, really helped me to put my new site design together quickly.

    This was going to be a “why can’t I work this out!” post, but its turned into a “its important to know…”! Anyway, I was struggling getting the reply to comment link to show, and after playing with the code for about an hour, I realised there was a setting in the admin panel under discussion to turn threaded comments on! Just a point to note if anyone else has the problem! Thanks again.

  9. my avatars dont show up, but just yesterday everything was good, it even doesnt work with pure shape templates
    i’m confused

  10. This tutorial rocks! I can’t stand the wordpress comments template and this post helped me to do things I wanted with comments I’m using a slightly modified version of this tutorial’s code on my personal site, and will shortly be using it on client’s sites. Thanks!

  11. I get these two errors:

    Warning: Cannot modify header information – headers already sent by (output started at /home/rigidkit/public_html/wp-content/themes/rigidkitchen/functions.php:25) in /home/rigidkit/public_html/wp-content/plugins/subscribe-to-comments.php on line 817

    Warning: Cannot modify header information – headers already sent by (output started at /home/rigidkit/public_html/wp-content/themes/rigidkitchen/functions.php:25) in /home/rigidkit/public_html/wp-includes/pluggable.php on line 865

    Using AJAX commenting and subscribe2comments

  12. Hey Ian,

    Where is that “” coming from at the top of your comments template file above? I don’t see the opening tag. At the very end of the file you close the #comments div so it’s not that.

    Is it just a typo? Thanks!

    1. ++++ Let’s try that again +++

      Where is that coming from at the top of your comments template file above? I don’t see the opening tag. At the very end of the file you close the #comments div so it’s not that.

      1. ++++ Okay… no code then.

        There’s a closing div.comments tag at the top and I’m just wondering if it is supposed to be there.

  13. I would like to inform you that when copying blocks it copies the line number also and makes it hard for ‘us readers that do not want to type everything out by hand.” I am not sure if this is the way you set it up so the reader has to do some work. FYI.

    1. I had the same problem in Firefox 3.6.8, so I opened the page in IE 8.0.6 and it worked fine – no line numbers!

      Despite my dislike for IE, on occasion it can be useful.

  14. First of all, thank you for this tutorial; it ROCKS!

    Second, I am when I submit a comment, either while logged in as admin or with new registration, the wp-comments-post.php comes up blank and nothing is being added to the database. I’ve been researching and going over the code for hours, but I can’t figure out what the problem is? Any ideas?


    ps. Running WordPress 2.9.2, MySql5

    1. Maybe a bit late to reply to this now, but hopefully it’ll help anyone else coming across this issue… The problem seems to stem from comment_post_ID hidden value being re-declared by the comment_id_fields() function. Also, where is $id from? Replaced with $post->ID and moved comment_id_fields() above this and it seems to work so far…

    1. Thanks Tim, I wasn’t sure whether to create comments.php or put that code in one of the existing files – browsing through the comments looking for exactly that answer!

  15. Nice job! This has been a great help for a lil’ project I’m finishing up, however it’d be nice if I could copy/paste directly from this page without having to do a regex to strip/fix converted entities and list numbering…

    Maybe you could do a follow-up post on how to drop code into a WP site that can be easily shared by others. 😉

  16. Hi Ian ,
    just one thing to ask you,
    when posting any comment to posts, and press submit button then it does nothing, could you help me.

  17. Going over this a couple of times, it looks like there is an extra which I can’t match to anything. At the top of comments.php, there is a which seems closed off after . However, I see at the end of the file a which seems to correspond to the comments div at the top. Am I reading all this wrong and just missing a div somewhere?


    1. You’re not missing a div tag.

      The first close div tag only gets output if the post is password protected AND the user isn’t logged in. The function then ‘returns’ and the rest of comments.php doesn’t get outputted.

  18. Mr. Ian,
    Thanks for this beautiful tutorial.
    I wish there will be a pdf version of this tutorial, it will be a very big help for those (like me) who do not own a computer. Yes, i just rent a pc to learn stuff like this.
    More Power.

  19. Ian, this and the previous tutorials have been fantastic and have taught me a lot about the structure of wordpress templates.

    The comments.php is still a pain in the rear but you have managed to demystify it a little!

    Kind Regards,


  20. Fantastic tutorial, thanks.

    I have a question regarding the comments:
    Why would nothing be happening when i try to post a comment? I’ve made sure the threaded comments option is selected in admin but whenever I try to comment nothing happens, all i get is the link to the anchor #respond in the browser bar…
    I’ve grabbed the code for both comments and header direct from the googlecode and still nothing happens.
    Do i need to include something else? The default theme works as it should…


  21. Hi there,

    So far I’m following, and all’s been ok; but I arrived at this section, and I’m not sure why it isn’t working. Comments simply do not show up at all.

    Here’s the weird thing: when I use the default “twentyten” theme, all the comments (from the dummy data) show up; but when I switch to my theme, OR the “Shape” theme, which I downloaded entirely and installed, none of them appear. Beneath the message “This page has comments”, nothing appears. Is this due to an error (in both themes?), or are things working as they should?

    1. I’ve figured it out!

      Whenever you call comments_template, you have to do it like this:

      comments_template(”’, true);

      This isn’t mentioned in the post, but it’s listed in the shape theme, which is available for download in the comments. I took that from there and it worked. Hopefully you’ll get to see my message somehow. 🙂

  22. Where does $comments_by_type get set? I must have missed something somewhere.

    I fixed it for myself by creating it and then filling it while doing the totals.

    $comments_by_type = array();
    foreach ( $comments as $comment ){
    get_comment_type() == “comment” ? ++$comment_count : ++$ping_count;
    $comments_by_type[get_comment_type()][] = $comment;

  23. How would you adapt the comment section to show an avatar OTHER than one for Gravatar? I tried using the FB connect plugin but it does everything BUT load the image. Any advice or do you know of any Facebook plugins that work with your script?

  24. nice tutorial, but i don’t understand at the last,, where is the comments template is wrapped?code in the end of section.
    thank you for great tutorials

    1. Hi there! Thanks for your question. 🙂 By default, comments_template() will use comments.php. If you’re using an alternative comments template, then in single.php, instead of calling comments_template(), you’d call comments_template( ‘/short-comments.php’ ). That should load your alternative comments template instead of the default comments.php template. I hope this helps!

Comments are closed.