set_post_thumbnail_size vs add_image_size

When an image is uploaded in WordPress, it is saved in its original size, and also as some resized copies in different sizes. In this way it becomes easy to use different sizes, of the same image, for different purposes.

By default, WordPress creates 3 copies in 3 different sizes:

  • 'thumb'
  • 'medium'
  • 'large'

The size in pixels for these 3 sizes can be set in the WordPress dashboard, under the menu Settings -> Media.

Now, the function add_image_size is used to register a new size, that adds to the 3 defaults.

Every size registered can be retrieved using its name, in some WordPress function, e.g. wp_get_attachment_image_src, wp_get_attachment_image, wp_get_attachment_link.

All these functions accept a parameter $size that should be the name of one of the registered sizes (one of the 3 standards, or one of the custom sizes registered with add_image_size).

If 'full' is used as $size argument, the original image is returned, the one not resized.

In addition to the functions mentioned above, there are two other functions that make use of image sizes: get_the_post_thumbnail and the_post_thumbnail.

These two functions get (the first) and echo (the second) the image that is set as “Featured Image” for a post.

What is returned (or echoed) by these functions is a full img html tag, something like

<img scr="http://www.example.com/wp-content/2013/08/image-200x200.jpg" />

So, which is the size used?

If a $size is passed as 2nd argument (1st is $postid), then these functions return the image in that size. Otherwise, these functions search for a image size registered with the name: post-thumbnail.

This is not one of the 3 default sizes, in fact, it is the 4th standard size (the 5th is considered full) and you can register it calling set_post_thumbnail_size.

So

set_post_thumbnail_size( $width, $height, $crop );

is a shortcut for

add_image_size( 'post-thumbnail', $width, $height, $crop );

If you haven’t called set_post_thumbnail_size (which means the size 'post-thumbnail' is not created), WordPress will use the size thumb, and if even this size is not available, WordPress will use the original image, the one not resized.

Registering custom image sizes can be very helpful when designing a theme, but it’s important not to abuse: every uploaded image is copied and resized for all the sizes registered, so registering a lot of sizes will heavily slow down the image uploading process.

A note:

Be aware that when WordPress creates scaled copies of an image, it never enlarges it, but only makes smaller copies: e.g. if the original image is 400x500px, and the ‘medium’ image size is 800x600px, medium size and larger are not created.

So registering an image size never gives the security that an image file for every size registered actually exists in the WordPress content folder. Even because registered image sizes easily change: changing settings, switching themes, etc.

When an image size changes, for any reason, the change has an effect on the images uploaded after that change; images uploaded before don’t change dimensions and are not rescaled and resaved.

If one needs to rely on specific image sizes after some images are already uploaded (e.g. after changing themes), then the plugin Regenerate Thumbnails will be a life saver.

Leave a Comment