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.

This post will show how to change and use the default WordPress image sizes, change built-in image sizes and add custom image sizes to a plugin or theme.


Images can be stored on a web server and be displayed on a web page. Different sized images are used to effect in different positions. Devices also differ in their capabilities to show larger images, so why allow the web browser to resize after downloading them? 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.

Image resizing is popularly done by using CSS attribute values or width and height parameters on the img tag, but the full image is still (down)loaded after which it is resized by the web browser. In other words, by using CSS and HTML to resize images, the server has to store fewer images (see later), but loading times will be longer.

WordPress automates the resizing/downscaling of larger images in a controlled manner and give users the ability to choose between them. This is done using functions. 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).

In WordPress, images are mainly displayed in one of two ways:

  • Using the Media Library -> Add Media button
  • Using PHP

Default WordPress 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 size variations of images uploaded using the Media Library. Each time an image is uploaded, WordPress will keep the original copy and create resized/cropped copies of the image. The cropped image files, together with the original file, will be stored in the/wp-content/uploads directory. Only images uploaded via the Media Library will be resized.

Apart from the ability to use the default image sizes via the Post Editor, some sizes will also be used by WordPress itself. For example, the Medium image size is used by the Media Library to display uploaded images. In addition to this, responsive themes will have more appropriate-sized images to choose from.

By default, the original image, and the three size variations will be selectable from the Post Insertion Attachment Display Settings.

WordPress Attachment Display Settings
The Attachment Display Settings showing the default WordPress image sizes. In this case, 2000 px x 2000 px image was uploaded.

WordPress uses basic rules to resize images. Image cropping will only take place when the image dimensions are larger than the set image sizes. If either the height or the width is larger, the image will be cropped. It will also be done proportionally, mainly in one of two ways (see later).

To insert the default images using PHP, the the_post_thumbnail() function can be used in the required theme template file:

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

The most important attribute to pass to the the_post_thumbnail() function is the public name of the image (set as a string value).

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

Upon deleting an image from the Media Library (by using the Delete Permanently link), all the default additional size variations of the image will also be removed.

The downside of additional image sizes

Additional image sizes take up more space on the website server. By using CSS attributes or HTML tags (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 the default sizes. When additional sizes are added (see later), even more space will be required to accommodate additional copies of these resized images.

Wordpress image size duplicates

Adding additional image sizes to WordPress

Although the default image size settings can be changed through the Media Settings section (not recommended for now, see later), additional image sizes can also be added to WordPress sites.

An 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. This is done using the wordPress add_image_size() function and adding the image to the $sizes array before filtering it through the image_size_names_choose function.

If set correctly, as with the default image sizes, various plugins (e.g. WooCommerce, Toolset, Shortcoder, etc.) will be able to use these additional resized images.

Adding additional image sizes using PHP and the add_image_size() function

Additional known image sizes can be added by modifying the (child) theme’s functions.php file.

Firstly, the support code for post thumbnails / featured images will have to be activated:

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

Additional image sizes are added using the WordPress add_image_size() function:

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

The add_image_size() function has four arguments:

  1. name, string (required) – the readable/public name of the image size
  2. width, integer (in pixels, optional)
  3. height, integer (in pixels, optional)
  4. crop, boolean (true/false, optional, default is false)

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)

Cropping options

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.

Various other cropping options are also available. Their settings can be generated and copied using the Simple Image Sizes plugin.

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 also be added to the Add Media dialog box (Post Insertion Attachment Display Settings Size dropdown menu).

WordPress Attachment Display Settings

This can be done in one of two ways:

  • Using a PHP code snippet in the (child) theme’s functions.php file
  • Using the Simple Image Sizes plugin

Using Simple Image Sizes to set the Attachment Display Settings Sizes

The simpler of the two options is by using the 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

Using PHP to set the Attachment Display Settings Sizes

To add image sizes to the Post Insertion Attachment Display Settings Size dropdown menu without using a plugin, the WordPress image_size_names_choose function can be used. This function uses the $sizes array to generate the list of image sizes that need to display on the Add Media dialog box.

To add entries to the $sizes array and then filter it through the image_size_names_choose function, the following code is added to the (child) theme’s functions.php file:

add_filter( 'image_size_names_choose' , 'prefix_image_size_menu_function' );

function prefix_image_size_menu_function( $sizes ) {
  return array_merge( $sizes, array(
    'featured-large' => __('640px by 294px'),
    'featured-small' => __('320px by 147px'),
  ) );

In this case, a function called prefix_image_size_menu_function() was used, but the user can create any function with a unique name. The $sizes array is passed into the function, which is merged with a new array after new items were added.

More than one image size can be added to the array at a time (in this case two were added). Make sure each array item ends with a comma, even if is the only or the last item on the list.

Regenerating old image sizes

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

The Simple Image Sizes plugin does a great job at regenerating image sizes. It is especially handy when a new image size was set, after which existing images need to be regenerated.

The Simple Image Sizes plugin functions from the WordPress Media Settings section (Dashboard -> 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
Simple Image Sizes allows a single image to be resized from the Featured Image section of the post/page editor.

Image size regeneration run after each time an image size was added or changed. Unfortunately, the plugin will not overwrite image sizes that are 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 the /wp-content/uploads directory, and also needs to be manually deleted if they are not being used anymore.

Using additional image sizes on WordPress

After an additional image size has been added to the functions.php file and its size has been (re)generated, it can be added to the theme template files:

// 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' );

After an additional image size has been added to the $sizes array and filtered through the image_size_names_choose function, they will be available for selection in the WordPress Post Editor.

WordPress Attachment Display Settings

Built-in image sizes

Built-in image sizes can be set by various plugins (e.g. WooCommerce) and themes (e.g. TwentyEleven theme). Without using WordPress PHP functions, the user won’t have much control over these image sizes – except if there are possible customisable settings areas available. The Simple Image Sizes plugin is great at identifying all built-in image sizes and can give some control over resizing them.

Note that Simple Image Sizes also adds built-in image sizes to WordPress. They are ‘1536×1536’ and ‘2048×2048’.

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.

Removing image sizes

When a default or built-in image size is not required, WordPress can be instructed not to use them anymore. This is done using the intermediate_image_sizes_advanced filter. Using this filter will prevent WordPress from automatically resizing new images upon uploading them.

By adding the following code to the (child) theme’s functions.php file, default image sizes can be removed:

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

Similarly, built-in image sizes can also be removed. By, for example, replacing ‘thumbnail’ with the Public name shown 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 size 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 webserver. 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 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 are already within one of the registered image sizes (either a default image size, added size, or one of the built-in image sizes). This will allow usage of this image instead (remember the_post_thumbnail( 'full' );), and not have any additional/unused images stored on the webserver.

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 image files from the /wp-content/uploads directory
  • Using the Simple Image Size plugin, (re)generating only the image sizes that need 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 is that these image sizes have 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 in 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

Discover the easy way to send bulk SMS from your PC, Mac or mobile device
Discover the easy way to send bulk SMS from your PC, Mac or mobile device
5 June 2020
Ad: Using the latest in technology, WinSMS offers cost effective messaging solutions that makers and business owners can use. With their online portal and API functionality, buying SMS bundles and sending them to recipients is more cost effective and easy to do. More…