Working with custom image sizes in WordPress

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

WordPress theme and plugin 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 regenerate 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 can be done by using CSS properties and HTML attributes, 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)
  • Large size (1024 x 1024 pixels)
WordPress default media settings
The three basic default WordPress image sizes are Thumbnail size, Medium size and Large size.

In addition to this, not shown here, WordPress also has the Medium Large image size (768 pixels wide).

The Medium Large size was introduced in WordPress 4.4 together with their responsive feature. I often use this size for in-post images.

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 (Full image size) and create resized/cropped copies of the image. By default, all the image sizes 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 six 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 shown by default.

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), parent themes (e.g. TwentyEleven theme) and WordPress itself. These are image sizes that theme/plugin developers need to know about before setting their own image sizes.

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.

Since WordPress 5.3, the 1536×1536 image size and 2048×2048 image size were added via /wp-includes/media.php.

Identifying image sizes

All WordPress images sizes are stored in one of two array variables, namely $default_sizes and $_wp_additional_image_sizes.

The easiest way to view these sizes are by using a plugin (e.g. the Simple Image Sizes plugin). Alternatively, WordPress PHP functions can be used.

The get_intermediate_image_sizes() function will return both  $default_sizes and $_wp_additional_image_sizes (which is a global WordPress variable). They are both arrays:

// Get all image sizes.
print_r( get_intermediate_image_sizes() );

Digging a bit deeper, the built-in and additional image sizes can be returned by using the wp_get_additional_image_sizes() function:

// Get built-in and additional image sizes.
print_r( wp_get_additional_image_sizes() );

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 developers, these functions can be added to the (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 filter hook (see Enabling additional image sizes in the WordPress post editor)

Quick note – be aware

Although it might not make sense at the moment, WordPress has a sneaky variable called $content_width that is needed by some themes to function. Its purpose is to set the maximum width of the main content area and oEmbed features, but it is also used by WP to override the maximum width set using the function and hooks discussed below.

The content width is set by themes in the following way:

if ( ! isset( $content_width ) )
    $content_width = 640;

Its value will be the maximum value of the image size values, even if the image size values are higher.

Adding additional image sizes using the add_image_size function()

The main step in adding additional image sizes to a WordPress site is by using WordPress’ add_image_size() function — which 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, yet.

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 image (1280 x 640 pixels), 'image-large'. The crop argument is set to true (cropped to fit)
  • A small 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

Being optional, this functionality 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 filter hook.

Unlike using theadd_image_size() function, the image_size_names_choose filter 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 filter hook uses the $sizes array to generate a list of image sizes that need to be displayed on the WordPress Post Editor interface:

// Adding additional image sizes names to Media drop-down.
function pre_add_image_settings( $sizes ) {
  return array_merge( $sizes, array(
    'image-large' => __('Large image'),
    'image-small' => __('Small image')
  ) );
}
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 it can be given any name that is unique.

The (empty) $sizes array is passed into the function, which is merged with the new array of added items. The final $sizes array is then filtered through the image_size_names_choose filter hook.

The image sizes need to be added in a specific way. In this case, 'image-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. If this is the case, make sure each array item ends with a comma, except if it is the only or the last item on the list.

If they are not going to be removed (see later), the function can also be extended to include the 1536×1536 image size and the 2048×2048 image size:

// Adding additional image sizes names to Media drop-down.
function pre_add_image_settings( $sizes ) {
  return array_merge( $sizes, array(
    'image-large' => __('Large image'),
    'image-small' => __('Small image'),

    '1536x1536' => __('1536x1536'),
    '2048x2048' => __('2048x2048')
  ) );
}
add_filter( 'image_size_names_choose' , 'pre_add_image_settings' );

Regenerating old image sizes

WordPress will only start to generate 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:

Using additional image sizes on WordPress

After an image size has been added and was filtered through the image_size_names_choose filter 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. I don’t even think there’s an easy way to remove default image sizes successfully in WordPress.
  • 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 WordPress, 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 default and built-in image sizes using the remove_image_size function)
  • image_size_names_choose filter 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 WordPress 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 an 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 image_size_names_choose filter hook (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:

// Removing built-in image sizes.
function pre_remove_image_size() {
  remove_image_size( '1536x1536' );
  remove_image_size( '2048x2048' );
}
// Fires after most of WP functionality has been loaded.
add_action( 'after_setup_theme', '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. Note that it uses unset() to remove the specified image size from the $_wp_additional_image_sizes array. With the PHP code above, the '1536x1536' and '2048x2048' built-in image sizes are being unset.

The remove_image_size() functions were 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 'after_setup_theme' filter 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 filter hook. Just make sure it wasn’t added by your own code in the first place:

function pre_remove_image_settings( $sizes ) {
  unset( $sizes['thumbnail'] );
  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_size_names_choose hook.

Unlike using the remove_image_size() function, the image_size_names_choose filter 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 & discuss

Your comment is important, but don't be a knob. Keep it constructive and polite.

One thought on “Working with custom image sizes in WordPress”

Leave a Reply

Your email address will not be published.

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
28 October 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…