logomichael sumner
Contact
AWWWards Nominee — Michael Sumner
Special Kudos Award Badge

Guide to WordPress Custom Post Thumbnail Sizes

You may have stumbled upon the fact that in the role as a theme developer it is a standard to build your theme with web performance in mind. This means to make sure that the images outputted in your theme are not in ‘full’ size if they might be more than 100 kilobytes.

Also, making use of WordPress’s functionality for the HTML image attribute srcset is another reason to be using the wp_get_attachment_image() function in outputting images.

Another usage would be in outputting blog posts with featured images. As a theme developer you want to make sure that you either specify: (a) one of the default post thumbnail sizes, or (b) create your own custom post thumbnail size.

Using a Default Post Thumbnail Size

There are cases wherein you might not have to use a custom post thumbnail size. However you may instead use a default post thumbnail size that will do perfectly for your requirements.

The default thumbnail sizes available for you to use are the following:

  • thumbnail (uses the size 150px × 150px)
  • medium (uses the size 300px × 300px)
  • medium_large (uses the size 768px × 0px)
  • large (uses the size 1024px × 1024px)

In these cases you can easily specify if you have a similar size to use for any one of these default thumbnail sizes. All you’ll have to do is use any one of the above mentioned strings in the $size parameter of the the_post_thumbnail() function.

You will notice that these default post thumbnail sizes are almost all square-cropped images. This is likely due to the maximal space of which an image can be outputted — a square. To make the most use of space, the decision was made to make these default post thumbnail sizes as square images.

When to Use a Custom Post Thumbnail Size

However, there are cases when you need to output an image that is not a square. Take for example that you have to add a featured image above your blog single article using the function the_post_thumbnail().

You can use the following code that will output a featured image of your article with the size 1024px × 768px:

add_image_size( 'single-feature', 1024, 768, true );

And quickly identifying what this means in layman’s terms:

  • add_image_size() — create a custom post thumbnail size
  • ‘single-feature’ — parameter $name, just a name of the custom post thumbnail size
  • 1024 — parameter $width, the width of the custom post thumbnail size
  • 768 — parameter $height, the height of the custom post thumbnail size
  • true — parameter $crop, means if to (a) hard crop, or (b) scale image into the custom post thumbnail size. More info in the WP Dev docs

As additional info: from the example the width and height specified were chosen (1024 × 768) as they are the common sizes to use for featured images. However this doesn’t have to mean that you can’t use any other size. Make sure you see what fits best for your theme design and use that.

How to Update Custom Post Thumbnails

As you will be testing out the new image sizes for your WordPress images you will notice that you may have trouble updating the width and height without changing the $name of the custom post thumbnail size.

Let us take for example that you have the old size:

add_image_size( 'single-feature', 1024, 768, true );

But now you need to update the size of this ‘single-feature’ thumbnail size to the following:

add_image_size( 'single-feature', 1366, 768, true );

You see that the change was in the width from 1024 to 1366. But as you refresh the template wherein this size is supposed to be displayed, it will still show its image with the width of 1024. How can this be fixed?

To remedy this, you will have to regenerate the thumbnail.

So to start off, make sure that you have updated your thumbnail width and height, then install the plugin Regenerate Thumbnails. Follow the instructions of the plugin and you will then have regenerated the thumbnail sizes successfully.

Regenerating all your images may take some time especially if your website has a lot of images in your Media Library.

Where to Place the add_image_size Function

The add_image_size() function will not work unless you place it properly within the WordPress after_setup_themeaction hook. This means that the following example code:

add_image_size( 'archive-featured', 792, 446, true );

Must be within the following action hook in your theme’s functions.php file under:

function ms_setup() {
    add_image_size( 'archive-featured', 792, 446, true );
}
add_action( 'after_setup_theme', 'ms_setup' );

Adding add_image_size in the Underscores Theme

A very popular starter theme called the Underscores Theme or _s theme has a good place to add your add_image_size() functions.

You can add the custom post thumbnail size function add_image_size() under the add_theme_support( 'post-thumbnails' ); line in the functions.php file of the Underscores theme.

The reason you can add the function add_image_size() under here is because it is already within the after_setup_theme action hook mentioned earlier.

Add Image Size Function Snippet for WordPress Themes

If you like, you can copy the snippet below for the add_image_size in the Underscores theme for your future reference:

/*
 * Custom post thumbnail sizes for use across the theme.
 *
 * @link https://developer.wordpress.org/reference/functions/add_image_size/
 */
add_image_size( $name, $width, $height, $crop );

Note: Please make sure you define the parameters used in the snippet to make sure you do not receive any PHP warning errors in your theme. The above snippet is used as a template for you to copy-paste into your theme functions.

Conclusion

Thank you for reading this article! Please let me know your thoughts and your setup on custom post thumbnail sizes.

If you enjoyed this article you might like to know the Theme mistakes in setting up custom post types. For one, don’t register custom post types in your theme!