post thumbnail

No, You Cannot Add Class to Post Thumbnail

Let me say it again and again until everyone reminds it: NO, You Cannot Add Classes to WordPress Post Thumbnail / Featured Image.

A common idea circulating the web states that you can, and everyone goes with their own snippet of PHP code to add in your Theme index.php. They are all the same, and they are all wrong:

if ( has_post_thumbnail() ) {      // check if the post has a Post Thumbnail assigned to it.
  the_post_thumbnail( 'full', array( 'class'  => 'class2Add' ) );  // Add a class to the featured image/main post thumbnail

Why is this wrong? Because the array of class(es) that you pass to the function the_post_thumbnail() replaces the size classes WordPress has generated for this thumbnail.

  • Calling the function the_post_thumbnail() will return an image with these classes: attachment-post-thumbnail size-post-thumbnail
  • Calling the function the_post_thumbnail(‘full’) will return an image with these classes: attachment-post-full size-post-full
  • and so on

How to actually Add classes to WordPress Post Thumbnails / Featured Image

If you pass some classes as arguments to this function, your post thumbnails will miss these classes. They may not be important, or your theme may not make any use of them, however if it does then you just introduced a bug in your site. The correct PHP code to add in your theme code is this one:

the_post_thumbnail( 'post-thumbnail', array( 'class'  => 'attachment-post-thumbnail size-post-thumbnail class2Add' ) );  // for thumbnails
the_post_thumbnail( 'large', array( 'class'  => 'attachment-large size-large class2Add' ) );                             // for large thumbnails
the_post_thumbnail( 'any_size', array( 'class' => 'attachment-any_size size-any_size class2Add' ) );                     // you get the idea

Replace post-thumbnail or large by any size you like among post-thumbnail, medium, large, thumbnail, full, or whatever size you defined with a snippet. You get the idea.

Why is this different from replacing?

Because replacing is NOT adding. Definition of adding in the Cambridge dictionary:

add, verb

A2 to put two or more numbers or amounts together to get a total:
If you add three classes to four classes you get seven classes.
Don’t forget to add on your travelling expenses/add your expenses on.

A2 to put something with something else to increase the number or amount or to improve the whole:
Add this code to your index.php to add a Class to the ones the Featured Image already has.
She’s added a Class to her list.
His colleagues’ laughter only added to (= increased) his embarrassment.

B1 to say another thing:
[ + that ] She was sad, she said, but added (= said also) that she felt she really added a class to the Post Thumbnail classes.
[ + speech ] “Oh, and thank you for all your help!” you added after reading this.


To put something with something else to increase the number: it’s different from replacing something by something else.

It’s not just semantic, it’s Elementary English Level (the “A2” tags).

When I searched how to add a class to my Post Thumbnails, I truly meant to add a class to the list of classes WordPress pre-generates for the image. I do not want to replace the classes linked to the size of the picture I have no idea where they come from. I want my thumbnails to keep the attachment-post-large and size-post-large classes or whatever other class WordPress or any plugin will add-up one day because this is the whole point of this software: everything is automatic. You should not know or guess the class names that need to be added if you want to add yours. What if tomorrow a new version of WordPress changes these class names or add more?

Why can’t I add a class to WordPress Post Thumbnails / Featured Image?

I looked into the WordPress code for you, because I don’t want you to listen to roukers. This is how it works:

  1. You call the_post_thumbnail() in your index.php
  2. the_post_thumbnail() is defined in wp-includes/post-thumbnail-template.php
  3. the_post_thumbnail() calls get_the_post_thumbnail()
  4. get_the_post_thumbnail() calls wp_get_attachment_image()
  5. wp_get_attachment_image() is defined in wp-includes/media.php
  6. wp_get_attachment_image() defines some classes in an array and returns the html code for the image:
function wp_get_attachment_image($attachment_id, $size = 'thumbnail', $icon = false, $attr = '') {

$default_attr = array(
  'src'	=> $src,
  'class'	=> "attachment-$size_class size-$size_class",
  'alt'	=> trim( strip_tags( get_post_meta( $attachment_id, '_wp_attachment_image_alt', true ) ) ),
$attr = wp_parse_args( $attr, $default_attr );
..more things added to $attr..

foreach ( $attr as $name => $value ) {         // constructs the html string to output your image
$html .= " $name=" . '"' . $value . '"';

return $html

As you can see, the classes programmatically generated against your image size passed as argument are used within this function, and are not exported.

There is NO WAY you can have such a global function or array that contains the classes you need to re-add to your image class list. You need to know how they are created and add them by hand, reproducing some of the WordPress inner code yourself. This is counter-productive but it’s the only way.

Wrapping up

So, next time you read someone claiming:

I made it! Add this example code to Add classes to the post thumbnail:

Oh no you didn't!

2 thoughts on “No, You Cannot Add Class to Post Thumbnail”

  1. Are there any issues with this approach?

    [php]//* Add class to featured images
    function bc_add_featured_image_class($attr) {
    $attr[‘class’] .= ‘ alignleft’;
    return $attr;

Leave a Reply

Your email address will not be published. Required fields are marked *