Adding Custom Images Sizes to the WordPress Media Library

Automatically uploading images into WordPress creates different sizes from the original but, unfortunately, it’s not a one-size-fits-all solution.

The default sizes that are created are thumbnail, medium, large and full-size. But, if you need a different size, such as for products in an eCommerce store, then you can create your own custom size to suit your needs.

In this post, I’ll show you how to create custom image sizes by registering them in your theme with code.

Adding Image Sizes to Existing WordPress  Themes

Before you dive right in and start adding code to your theme, you should create a child theme if you’re working with a pre-existing theme. This prevents all your changes from being erased if you apply updates to your theme once they become available.

For details, check out these posts:

Once you have created a child theme, you can continue editing. If you’re working on a theme from scratch, you can skip this step and start adding the code below.

Moving forward, I’ll assume you’re creating your own theme so if you’re editing a pre-existing one, you can make sure the document has the necessary code below. If you don’t see similar code being used, then add it.

Registering Image Sizes in WordPress

Start by opening or creating your theme’s functions.php file, then setting up your theme such as in the example below that was extracted from the default Twenty Seventeen theme:

As the comment explains, you’re able to register support for WordPress features you want to use in your theme such as featured images, post formats, a custom header and other similar options.

There’s one feature you absolutely need to register in order to be able to create custom image files and that’s post thumbnails:

After version 2.9 of the WordPress core, post thumbnails have been renamed “featured images” in the back end, but it’s (confusingly) still referred to by its original name in the file’s code. These terms can be used interchangeably, though, depending on your audience, it can be confusing for some.

Next, you can add your custom image sizes with the add_image_size function. This is the basic structure you need:

Be sure to change themename to your real theme’s name. Replace new-custom-size with a descriptive name for your image size. While you can use almost any name, these ones are off-limits because they’re reserved by the default image sizes mentioned earlier: thumb, thumbnail, medium, large, post-thumbnail.

Also, you can set the custom image size’s width, height and crop mode.

You can change the width and height to the dimensions you need. While these are pretty self-explanitory, the crop mode isn’t and it also needs replacing.

There are a few options for cropping your images:

  • Hard crop – To enable this, replace crop mode with true. It cuts a larger image to the exact width and height that’s defined so it fits perfectly into your design, though, it may not necessarily crop the image proportionately.
  • Soft crop – This is the default setting and it’s enabled by removing , crop mode. It proportionately crops an image, but the image heights may vary if they were originally different sizes.
  • Unlimited height – By deleting , height, crop mode your custom image can have an unlimited height. This is particularly useful for infographics.

You can repeat the line in the code snippet above to register as many custom image sizes as you need. Don’t forget to edit it to meet the specifications you need.

You can continue to add support for the features you need and when you’re done, include the after_setup_theme hook:

Keep in mind that themename should be changed to the actual name of your theme and it can include underscores. Just be sure to use this name consistently throughout this file.

For details on the proper syntax and structure for your theme’s functions.php file, check out The Ultimate Guide to the WordPress functions.php File and WordPress Development for Beginners: Building Themes.

Adding Custom Image Sizes to the Media Uploader

Since version 3.3 of WordPress, you can also add your custom image sizes and make them selectable when you’re editing posts and pages in the back end.

Once you add the code below, you can go to Posts > Add New or Pages > Add New and click the Add Media button. Then, you can upload an image and choose your custom image size before adding it to the post or page.

The new custom image size appearing under size in the media uploader.
An example custom image size appearing in the media uploader.

You can change my_custom_sizes to something more meaningful to you to describe your custom sizes that you define. You can also change new-custom-size and New Custom Size Name to something more descriptive for your image size.

It doesn’t matter what name you pick, as long as it makes sense to you and your users. Keep in mind that the name you choose to replace New Custom Size Name should be human-readable since this is what’s displayed in your site’s backend.

You can also repeat line five if you want to add more than one custom size.

Now, you can finish up your functions file with anything else you want to include, then save it.

Custom Image Sizes in Theme Templates

You can also add your custom image size in your theme’s post templates as the featured image with the code below from the WordPress Codex’s Code Reference page:

Be sure to change new-custom-size to the actual name of your custom image size.

You can also add it to any page or post template, without setting it as a featured image with the code below, also from the WordPress Codex’s Code Reference page:

Don’t forget to replace new-custom-size with the real name of your image size as you have done before and up until this point.

This option is particularly useful for eCommerce page templates. You can add a specific image size that’s best suited for displaying products in different sizes from thumbnails to larger sizes.

Regenerate Thumbnails

If you created a child theme to create custom image sizes for a parent theme you were actively using, there’s one more step involved. You need to reset your original image sizes and refresh them so your custom sizes take effect.

The easiest and fastest way of doing this is to use the Regenerate Thumbnails plugin. It’s free, updated regularly and it’s also of high-quality. It installs like most other plugins and works like a charm.

You can check out the plugin page for Regenerate Thumbnails for details on how to use it.

Wrapping Up

The default images sizes available in WordPress are useful, but it can be handy to create custom image sizes for your theme. Fortunately, with the code above, you can add your own custom sizes to the media uploader as well as any page or post template you want.

Don’t forget, if you run into troubles while trying to add your own custom image sizes in WordPress, you can ask our expert support team for help 24/7 – and for free!

Jenni McKinnon
Did you try adding your own custom image sizes to your theme? How did it go? Do you find this WordPress feature useful? How have you used it or how do you plan on using it? Feel free to share your experience in the comments below.