Working with custom image sizes in WordPress

Working with custom image sizes in WordPress
Published: by
Last updated:

Often website theme styling and development requires different sized images in various locations. There are various ways to achieve this. This post is about creating and working with custom image sizes in WordPress.

This is an ongoing post. Please suggest corrections, explanations, etc. in the comment section at the bottom of this page.

WordPress uses functions to set image sizes. For this post it is assumed that image size functions are either set by WordPress itself (default image sizes), by themes or plugins (built-in image sizes), or by the web developer (additional image sizes). Post type (e.g. posts and pages) images are mainly added in one of two ways:

  • Using Media Library through the Add Media button
  • Through PHP

Default image sizes

By default, WordPress has 3 different image sizes:

  • Thumbnail size (150 x 150 pixels)
  • Medium size (300 x 300 pixels)
  • Large size (1024 x 1024 pixels)

WordPress default media settings

The default WordPress image sizes are basically size variations of each originally uploaded image through the Media Library. In other words, each time an image is uploaded, WordPress will keep the original copy and resize/crop the image to these size variations. The cropped files, together with the original file, will be stored in the/wp-content/uploads directory of the website. Only images uploaded via the Media Library will be resized.

WordPress uses basic rules to resize these images to the default sizes mentioned above.

WordPress attachment display settings

Apart from the ability to use the default image sizes in post types, some of them will also be used by WordPress itself (e.g. the Medium image size is used by the Media Library to display uploaded images). By default, the original image, and the three size variations will be be selectable from the Post Insertion Attachment Display Settings. To insert these images using PHP the following code can be used in the required template file:

the_post_thumbnail( 'thumbnail' );
the_post_thumbnail( 'medium' );
the_post_thumbnail( 'large' );
the_post_thumbnail( 'full' );

In order to speed-up the loading time of a web page, it makes more sense to have (especially large) (re)sized images pre-loaded instead of full images being resized while the page is loading.

By using CSS (e.g. the width and height parameters on the img element), fairly similar visual results can be achieved, but the full image is still loaded after which it is resized by the browser. In other words, by using CSS to resize images, your server has to store less images (see later), but loading times will be longer.

WordPress uses, among other ways, the functions.php file to do the resizing behind the scenes without the user even knowing it. This happens each time an image is uploaded. By using a FTP client (e.g. Eclipse), these resized images will be visible in the /wp-content/uploads directory of the website.

Upon deleting the images from the Media Library (Delete Permanently), all the default additional size variations of the files will also be removed.

The downside

Additional image sizes take up more space on the website server. By using CSS (mentioned earlier), less server space is used, but loading times will be longer. Each time a new image is uploaded to the site, WordPress will convert it to these default sizes. When additional sizes are added (see later), more space will be required to accommodate additional copies of these resized images.

Wordpress image size duplicates

How images are resized

The WordPress cropping functions will only crop images with dimensions larger than the image sizes. If either the height or the width is larger, the image will be cropped proportionally (see later).

Additional image sizes

Although the default image size settings can be changed through the Media Settings section (not recommended for now), additional image sizes can also be added to WordPress sites. A very effective way to do this is by using a combination of modifying the (child) theme’s functions.php file and using the Simple Image Sizes plugin. As with the default image sizes, various plugins (e.g. WooCommerce, Toolset and Shortcoder) will be able to use these additional resized images. The resized images can also be added using PHP (see later).

Adding known additional image sizes

Additional known image sizes can be added by modifying the (child) theme’s functions.php file. The functions.php file can be opened/edited using a FTP client (e.g. Eclipse).

Firstly, support for post thumbnails / featured images will have to be activated. To do that, add the following code to the bottom of the functions.php file.

// Enable feature image support
add_theme_support( 'post-thumbnails' );

Look at the following code example before adding your required values:

// Add featured image sizes
add_image_size( 'featured-large', 640, 294, true ); // width, height, crop
add_image_size( 'featured-small', 320, 147, false );

add_image_size() has four arguments:

  1. name, string (required)
  2. width, integer (in pixels, optional)
  3. height, integer (in pixels, optional)
  4. crop, boolean (true/false, optional)

With the code snippet above, two additional image sizes are set:

  • A large featured image (640 x 294 pixels), featured-large. The crop argument is set to true. (cropped to fit)
  • A small featured image (320 x 147 pixels), featured-small. The crop argument is set to false. (proportionally resized to fit inside dimensions)

The crop options will work as follows:

1) True: The image will be cut to the predefined shape/size. Also referred to has “hard cropping”. This will no longer maintain the same shape as, or contain the full contents of, the original image.

Example image with dimensions of 1024 x 512 pixels.
Working with custom image sizes in WordPress - hard crop
Example image after “hard cropping” now with dimensions of 512 x 256 pixels.

2) False (default, or no value): The image will be resized. Also referred to as “soft cropping”. This will maintain the proportions of the image. In other words, the entire image will be resized according to the specified dimensions without changing the shape of the image, or cut any bit out of it.

Working with custom image sizes in WordPress - soft crop
Example image after “soft cropping” now with dimensions of 512 x 256 pixels.

Known additional image sizes can be added in PHP as follows:

// Display post's featured image, in 'featured-image-large' size

// Inside the loop
the_post_thumbnail( 'featured-image-large' );
// Outside the loop
echo get_the_post_thumbnail($page->ID, 'featured-image-large');

Enabling additional image sizes for post content

For simplicity, and in order to keep track of the default image sizes used on a website, the default and added image sizes can be added to the Post Insertion Attachment Display Settings.

WordPress attachment display settings

To be able to use this function, additional code needs to be added, but is simpler to use a plugin named Simple Image Sizes.

Simple Image Sizes plugin

After Simple Image Sizes has been installed and activated, ‘Show in post insertion’ needs to be activated in the Settings > Media section.

Show in post insertion

Regenerating the old image sizes

By adding additional image sizes to WordPress, existing images (those uploaded prior to updating the functions.php file) will not be resized. The same problem will exist when the dimensions of default image sizes have changed.

The Simple Image Sizes plugin also does a great job at regenerating image sizes. After the plugin has been installed and activated, this is done from the Media Setting section (Settings -> Media). Simple Image Sizes will go through the (child) theme’s functions.php file and display all the additional registered image sizes. It will also work with built-in image sizes.

To start regenerating image sizes, refer to the Thumbnail regeneration section. Choose the desired image size(s) and the post type(s) to be (re)generated before pressing the Regenerate Thumbnails button at the bottom. Individual images can also be resized from the Featured Image section in the post/page editor.

Single image resize
Single images can be resized from the Featured Image section of the post/page editor.

The plugin needs to be run after each time an image size is added or changed, but will unfortunately not remove the old custom image sizes from the /wp-content/uploads directory of the website. It will also not overwrite image sizes that is already present, which will save time, but these images need to be manually deleted first. Similarly, when an image has been deleted from the Media Library, some of the older built-in image sizes might remain in this directory, and also needs to be deleted manually if they are not being used (anymore).

Built-in image sizes

Built-in image sizes can be set by various plugins (e.g. WooCommerce) and themes (e.g. TwentyEleven theme). We don’t have much control over these image sizes, except if there are possible customisable settings areas available. Simple Image Sizes is a great plugin to use to identify built-in image sizes and can give some control over resizing them.

Another important aspect to consider about built-in image sizes is that they might be targeted for specific post types. WooCommerce, for example, only targets Product post types, but its built-in image size support will resize images for all post types. It might be a good idea to check each new plugin’s built-in image sizes early on so that they can be disabled/removed (see later) and only be (re)generated for its intended post type.

Mobile responsiveness

In the later versions of WordPress, they have made it very easy to still maintain responsiveness. It should work out-of-the-box as with the default image sizes.

Removing image sizes

When an image size is not required, WordPress can be instructed not to use them anymore. This will prevent WordPress from automatically resizing new images upon uploading them. If the removed image size is not available in the /wp-content/uploads directory, it will also not be available from the Post Insertion Attachment Display Settings anymore. By adding the following code to the (child) theme’s functions.php file, the default image sizes can be removed:

add_filter( 'intermediate_image_sizes_advanced', 'prefix_remove_default_images' );
// Remove default image sizes here. 
function prefix_remove_default_images( $sizes ) {
 unset( $sizes['thumbnail']); // 150px
 unset( $sizes['medium']); // 300px
 unset( $sizes['large']); // 1024px
 return $sizes;

Similarly, built-in image sizes can also be removed. By, for example, replacing ‘thumbnail’ with the Public name showed for the image size in the unset function line above, the corresponding image size will not be used anymore.

Be careful when removing image sizes, especially the default image sizes. As mentioned earlier, the default image sizes are not only used in post types, but also by the WordPress back end. The medium (300 x 300 px) and large (1024 x 1024 px) image sizes are, for example, used in the Media section as thumbnails and post editor. Similarly, the medium size is an internal image sizes that is used for mobile responsiveness and should also not be removed. Caution must also be taken when removing image sizes on older WordPress websites, as they might have been used on older post types.

What to do with this information

After some planning, the exact required image sizes can be determined. Ideally, only those image sizes, together with the original image should be stored on the web server. If similar, the default image sizes can be reconfigured in the Media Settings section.

Although bigger is better, the file size (e.g. in KB or MB) of the image needs to be considered too. Using a properly configured quality:size ratio when uploading website images can significantly reduce image file sizes while still having a decent quality.

Try to do some manual cropping yourself. Use the largest set WordPress image size for the original image. In other words, use dimensions that is already within one of the registered image sizes (either an default image size, added size, or one of the built-in image sizes). This will allow usage of this image in stead (remember the_post_thumbnail( 'full' );), and not have any additional/unused images stored on the web server.

Workflow for changing/adding additional image sizes

  • Disabling support for the unused image sizes (see Removing image sizes)
  • Adding only the required additional image sizes (see Additional image sizes)
  • Manually removing old/unused, resized images from the /wp-content/uploads directory
  • (Re)generating only the image sizes that needs to be added for the post type that will need them

What about built-in image sizes for specific post types?

An interesting example of built-in image sizes is where these image sizes are not needed for all posts types. Take WooCommerce’s built-in shop_single size as an example. WooCommerce is a commerce plugin that creates a Products post type for a WordPress website.

Just like the post types, posts and pages, are different w.r.t. their layout and image sizes, these are also different from Products. The chances that a developer might want to use the shop_single image size on posts and pages is small. If this is the case (i.e. those images are not going to be used on post and page post types), then it makes no sense for WordPress to generate the shop_single image size for posts and pages too (it only needs to be generated for the Product post type.

WooCommerce sample

In this case, the shop_single image size needs to be unset. This will prevent WordPress from generating these image sizes with each image upload. The shop_single image size can then be generated using Simple Image Sizes for Products only. The obvious downfall being that these image sizes has to be regenerated manually after product images have been uploaded.

Bypassing image sizes

In cases where only the original size of an image is required, image resizing can be bypassed by manually uploading the image using and FTP client (e.g. Eclipse). A simple way would be, for example, to create a new directory under the /wp-content/uploads directory, e.g. /wp-content/uploads/singles. This will unfortunately mean that the image directory will have to be set manually each time the image is used.

About the author
Renier busies himself with improving his English writing, creative web design and his websites, photoshopping, micro-electronics, multiple genres of music, superhero movies and badass series.
Behind the Scenes is a free, informative website. If you find value in any of our content, please consider making a donation to our cause.
Donate via PayPal

Save, share & Disqus

Use the buttons below, on the left or the bottom of this page to share this post. Your comment is important, but don't be a knob. Keep it constructive and polite.

Comment via Disqus

Disqus is a worldwide comment hosting service for web sites and online communities. This secure platform ensures a pleasant commenting environment which is manageable from one account. Use the Login button to sign up.

More website development related posts

Try one of’s online software and skills learning courses
Try one of’s online software and skills learning courses
15 October 2019
Ad: Improve your knowledge on anything from programming to business skills with’s huge range of professional video courses. More…
Using the Media Library Assistant plugin for WP
Using the Media Library Assistant plugin for WP
5 January 2019
WordPress websites with a large amount of Media content can become overwhelming to manage. With expanding libraries, images and other media can start to disappear in a sea of files which can make finding them very difficult. With the Media Library Assistant plugin for WordPress, searching and organising Media files becomes a breeze. More…
Disabling the Gutenberg Editor in WordPress 5
Disabling the Gutenberg Editor in WordPress 5
9 December 2018
Most WordPress users are probably happy with regular updates on their favourite content management website software, but for me, a striking difference starting at WordPress 5 was the Gutenberg Editor instead of the, now, Classic Editor. Without going into to much of a discussion, this post will show how disable the Gutenberg Editor. More…