Custom WordPress thumbnail (featured images) sizes

November 5, 2016 WordPress PHP

When working with WordPress, there are times that we need to include images at sizes that do not come out of the box with the platform. The ones that come with it, although standard, sometimes are either too big or not big enough. This article is going to focus on how to add (or register) image sizes using WordPress's included functions documented in the Codex.

When a user uploads an image into the Media Library, WordPress resizes images to three varying sizes: thumbnail, medium, large and keeps the original size called full. The sizes dimensions can be changed in the Settings section of the admin panel.

WordPress's default sizes

These sizes can be changed, but won't apply to older images that have been saved in the Media Library. So think about the sizes you're going to be using throughout the site before creating your theme. This will make it so that images that are added after your theme is activated will be resized/cropped after being uploaded.

Edit your theme's functions.php file

In your theme's functions.php file, we're going to add all of the required function calls to add new image sizes. Here are the functions we're going to cover (if you want to do some light reading after this one).


Here's the completed code. You can copy this and throw it right in your functions.php theme file.

add_action('after_theme_setup', function() {

    // Add theme support to to the theme

    // Add featured post image size
    // will force crop image
    add_image_size('blog-preview-featured', 656, 298, true);

    // Add blog preview (the blog reel) image size.
    // will force crop image
    add_image_size('blog-preview-small', 410, 230, true);

    // Main image size used in single pages
    add_image_size('blog-main', 855, 575);

Let's break it down

Looking at the above, its not that scary. You can see that we first create a closure that adds functionality and theme support to our WordPress theme. The hook use is after_theme_setup.

add_action('after_theme_setup', function() {


Here is the main function callback that willhook into your theme. This fires right after you hit the activate button on your theme settings page as well as every time WordPress loads the theme at runtime. Right after this, we have to make sure that our theme supports thumbnails (or featured images).


This seems pretty straight forward right? Learn more about Post Thumbnails. Next we're going to use the add_image_size() function to register each custom size we want to use within our theme.

In the above examples, you can see how each is used.

// Add featured post image size
// will force crop image
add_image_size('blog-preview-featured', 656, 298, true);

Essentially, we tell WordPress the new size's name and what its dimmensions will be. The fourth argument asks if we want to force crop the image to that size. By default, it's set to false. Its set it to true in two of the examples above. This can also take an array as the value. The array is the position of the crop: array('top', 'left').

Check out the documentation on the WordPress Codex.

How to use it in your theme.

Now that you have the image sizes registered, you can use them throughout your code with the_post_thumbnail() (codex). Some functions that work with images, may also take a size argument. Because these sizes are registered throughout the WordPress instance globally, they will be available to those functions as well. For example, you can use get_the_post_thumbnail(), the_post_thumbnail() or wp_get_attachment_image_src().

Most of the time, you will find yourself using it like so:

// Will print the large size

// Will print our custom size