Working with custom image sizes in WordPress

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

WordPress theme developers often require different sized images in various locations. There are various ways to achieve this. This post is about creating and working with image sizes in WordPress.

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

While explaining the process, functions and variables, this post will show how to use the default WordPress image sizes, set additional image sizes, unset built-in image sizes and how to generate image sizes.

Introduction

Images can be stored on a web server and be displayed on a web page. Different sized images are used to effect in different locations. Devices also differ in their capabilities to show larger images, so why allow the web browser to resize images after they have been downloaded? In order to speed up the loading time of a web page, it makes more sense to load smaller versions of (especially large) images instead of full images.

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, 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 theme developer (additional image sizes).

Default WordPress image sizes

By default, WordPress has 4 different image sizes:

  • Thumbnail size (150 x 150 pixels)
  • Medium size (300 x 300 pixels)
  • Medium Large size (768 pixels wide)
  • 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 three of the four size variations will be selectable from the WordPress Post Editor.

WordPress Attachment Display Settings
Showing the image size related settings in the WordPress Post Editor. Image Attachment Display Settings for Classic Editor (left) and Image Settings for Gutenberg (right). Both show the default WordPress image sizes on their drop-down list. Note that the Medium Large image size is not available.

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 (see later).

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

The downside of additional image sizes

Resized images 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

Built-in image sizes

Built-in image sizes are those enabled by activated plugins (e.g. WooCommerce) and parent themes (e.g. TwentyEleven theme). These are image sizes that theme/plugin developers need to know about before setting their own image sizes.

The Simple Image Sizes plugin is great at identifying all built-in image sizes. Note that Simple Image Sizes also sets built-in image sizes to WordPress. They are '1536x1536' and '2048x2048'.

Another important aspect to consider about built-in image sizes is that they might be targeted at 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.

Adding additional image sizes to WordPress

Additional image sizes can also be assigned to a WordPress site. As with the default WordPress image sizes, additional image sizes are set using PHP functions. For theme/plugin developers, these functions can be added to the plugin or (child) theme’s functions.php file. The two main WordPress functions to set additional image sizes are:

  • The add_image_size() function (see Adding additional image sizes using the add_image_size function)
  • The image_size_names_choose hook (see Enabling additional image sizes in the WordPress post editor)

Adding additional image sizes using the add_image_size function() (required)

The main step in adding additional image sizes to a WordPress site is by using the add_image_size() function. This function basically adds the image size to the global WordPress $_wp_additional_image_sizes array.

After an additional image size has been set using theadd_image_size() function, uploaded images will be resized automatically, but they will not be selectable from the WordPress Post Editor.

Adding additional image sizes using the WordPress add_image_size() function:

// Add additional image sizes.
add_image_size( 'image-large', 1280, 640, true );
add_image_size( 'image-small', 640, 320, false );

or, more efficiently:

function pre_add_image_size() {
  // Add additional image sizes.
  add_image_size( 'image-large', 1280, 640, true );
  add_image_size( 'image-small', 640, 320, false );
}
// Fires after the theme is loaded.
add_action( 'after_setup_theme', 'pre_add_image_size' );

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 PHP code above, two additional image sizes are set:

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

Cropping options

The add_image_size() function 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 in the WordPress Post Editor (optional)

As we know, the default WordPress image sizes can be inserted into Post/Page content using the Post Editor (done using the Attachment Display Settings (Classic Editor) or Image Settings (Gutenberg)).

WordPress Attachment Display Settings

Although optional, this functionality still needs to be set for the additional image sizes. Additional or built-in image sizes images can be added to the WordPress Post Editor interface using the WordPress image_size_names_choose hook.

Unlike using theadd_image_size() function, the image_size_names_choose hook has no effect on the generation of image sizes, but purely on displaying them in the Post Editor. Only images that were uploaded and/or regenerated after the add_image_size() function was set will display in the Post Editor (see Regenerating Old Image Sizes below).

The WordPress image_size_names_choose hook uses the $sizes array to generate a list of image sizes that need to be displayed on the WordPress Post Editor interface:

function pre_add_image_settings( $sizes ) {
  return array_merge( $sizes, array(
    'image-large' => __('Large image'),
    'medium_large' => __('768px wide')
  ) );
}
add_filter( 'image_size_names_choose' , 'pre_add_image_settings' );

In this case, a custom function that handles the $sizes array was created. This function was called pre_add_image_settings(), but the user can give it any name (as long as it is unique).

The current WordPress $sizes array is passed into the function, which is merged with the new array after new items were added. The final $sizes array is then filtered through the image_sizes_names_choose hook.

The image sizes need to be added in a specific way. In this case, 'featured-large' represents the readable name of the image size (which is used as the identifier), and Large image' represents the name that will be displayed on the dropdown menu.

More than one image size can be added to the $sizes array at a time. Make sure each array item ends with a comma, except if it is the only or the last item on the list.

As mentioned earlier, although WordPress creates the Medium Large image size (768 pixels wide), by default this image size is not selectable from the Post Editor. To make the medium_large image size selectable from the Post Editor, the following line can be added to the pre_add_image_settings() function above:

'medium_large' => __('768px wide')

Regenerating old image sizes

WordPress will only start to generate images to the required image sizes after they have been set/updated. Unfortunately, all images that were uploaded before a new image size has been set/updated will need to be regenerated.

Fortunately, there are a couple of easy-to-use WordPress plugins that are suited perfectly for this job. They include:

Simple Image Sizes plugin

To start regenerating old 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. While the Simple Image Sizes plugin is activated, 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.

Unfortunately, the Simple Image Sizes plugin will not overwrite image sizes that are already present. This will save time, but these images variations need to be manually deleted first. Similarly, when an image has been deleted from the Media Library, some of the older built-in or added image sizes might remain in the /wp-content/uploads directory. If not being used anymore, they will also need to be deleted manually.

Using additional image sizes on WordPress

After an image size has been added and was filtered through the image_size_names_choose hook, it will be available for selection in the WordPress Post Editor Attachment display settings (Classic Editor) and Image Settings (Gutenberg).

WordPress Attachment Display SettingsOnly images that were uploaded and/or regenerated after the add_image_size() function was set will display in the Post Editor (see Regenerating Old Image Sizes earlier).

Removing image sizes

When an image size is not required it is best to remove it from WordPress. Before removing any image size, it is important to distinguish between default image sizes, built-in image sizes and additional image sizes:

  • As mentioned earlier, it is not a good idea to remove default WordPress image sizes.
  • Additional image sizes (added by the theme developer) can be removed by simply deleting its code from the functions.php file and deleting the file variations from the /wp-content/uploads directory.
  • Built-in image sizes (added by plugins or a parent theme) need to be unset and its file variations need to be deleted from the /wp-content/uploads directory.

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 in the 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.

As with adding additional image sizes, unsetting them also needs to be done using WordPress functions. For theme/plugin developers, these functions can be added to the plugin or (child) theme’s functions.php file. The main WordPress functions used to unset an image size are:

  • Theremove_image_size() function (see Removing built-in image sizes using the remove_image_size function)
  • image_size_names_choose hook (see Disabling image sizes in the WordPress Post Editor)

Removing built-in image sizes using the remove_image_size function()

As with adding additional image sizes, the main step in removing built-in image sizes from a WordPress site is by using the remove_image_size() function. This function basically removes the image size from the global WordPress $_wp_additional_image_sizes array.

After a built-in image size has been unset using theremove_image_size() function, images will no longer be resized when they are being uploaded. If the image size was added to the $sizes array (see earlier), they will still be selectable from the WordPress Post Editor (see Disabling image sizes in the WordPress Post Editor below).

Removing built-in image sizes using the WordPress remove_image_size() function:

function pre_remove_image_size() {
  // Remove built-in image sizes.
  remove_image_size( '1536x1536' );
  remove_image_size( '2048x2048' );
}
// Fires after most of WP functionality has been loaded.
add_action( 'init', 'pre_remove_image_size' );

In its simplest form, the remove_image_size() function only takes the readable/public name of the image size as an argument. With the PHP code above, the '1536x1536' and '2048x2048' built-in image sizes that were set by the Simple Image Sizes plugin are being unset.

The remove_image_size() functions need to be added to a custom function, in this case, called pre_remove_image_size(). This custom function can be given any name, as long as it’s unique. The function is then added to the WordPress 'init' hook.

Disabling image sizes in the WordPress Post Editor

To stop an image size from showing in the WordPress Post Editor, it needs to be removed from the $sizes array and filtered through the image_size_names_choose hook:

function pre_remove_image_settings( $sizes ) {
  unset( $sizes['1536x1536'] );
  unset( $sizes['2048x2048'] );
  return $sizes;
}  
add_filter('image_size_names_choose', 'pre_remove_image_settings');

In this case, a custom function that handles the $sizes array was created. This function was called pre_remove_image_settings(), but the user can give it any name (as long as it is unique).

The current $sizes array is passed into the function, from which the required image sizes are removed/unset. The final $sizes array is then returned and is filtered through the image_sizes_names_choose hook.

Unlike using the remove_image_size() function, the image_size_names_choose hook does not have an effect on the generation of images, but purely on displaying them in the Post Editor.

Note that only images that were removed and/or regenerated after the remove_image_size() function was set will stop displaying in the Post Editor.

Bypassing image resizing

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

Try one of Lynda.com’s online software and skills learning courses
Try one of Lynda.com’s online software and skills learning courses
11 August 2020
Ad: Improve your knowledge on anything from programming to business skills with Lynda.com’s huge range of professional video courses. More…