The Complete Guide to Adding Custom Image Sizes in WordPress (2024)

Hey there, WordPress user! Are you tired of your images not quite fitting your theme‘s layout? Want to speed up your site by serving perfectly sized thumbnails? You‘ve come to the right place.

In this guide, we‘ll dive deep into the world of WordPress image sizes. I‘ll show you how to take control by adding your own custom dimensions in just a few lines of code.

By the end, you‘ll be a master of your media library, delivering pixel-perfect images to your visitors. Let‘s get started!

Why Custom Image Sizes Matter

First off, why should you care about custom image sizes? After all, WordPress automatically creates several sizes for each image you upload. Isn‘t that enough?

Well, not always. While the default sizes cover common use cases, themes often require more specific dimensions for featured images, thumbnails, sliders, and more. Trying to fit a square peg in a round hole just leads to awkward cropping and wasted pixels.

More importantly, serving oversized images is one of the biggest performance killers for WordPress sites. Let‘s say your theme displays featured images at 500px wide. If you upload a 2500px wide photo, that‘s 5x more data than necessary being loaded on every page!

Consider these stats:

• The average image weight on web pages has more than doubled in the past 5 years (HTTP Archive)
• Over 50% of pages have images larger than 4MB (Backlinko)
• Every second of delay in page load decreases conversions by 4.4% (Portent)

By generating custom image sizes tailored to your design, you ensure each image is perfectly optimized, resulting in faster load times, better SEO, and happier visitors. It‘s a win-win!

How WordPress Generates Image Sizes

Before we get into adding custom sizes, let‘s take a quick look at how WordPress handles images by default.

When you upload an image, WordPress automatically generates several copies in different dimensions:

You can see these sizes in your Media Library by selecting an image and clicking "Edit Image":

WordPress themes and plugins can also register their own sizes using the add_image_size function (which we‘ll cover in depth next). For example, a portfolio theme might add a "portfolio-thumbnail" size, or a slider plugin could include sizes for different slider layouts.

The key thing to understand is that image sizes are set in stone at the time of upload. WordPress doesn‘t dynamically resize images on the fly. If you decide later that you need a 400×400 size, you‘ll need to regenerate thumbnails for existing uploads (more on that later).

Adding Custom Image Sizes

Alright, let‘s get down to brass tacks. To add your own custom image size, you‘ll add a snippet of code to your theme‘s functions.php file.

The basic syntax looks like this:

add_image_size( ‘my-custom-size‘, 500, 500, true ); 

Breaking that down:

• ‘my-custom-size‘ is the name you want to give your custom size. This is how you‘ll reference it in your theme templates. Use a descriptive name so it‘s clear what the size is for.
• 500, 500 are the width and height in pixels. In this example, we‘re creating a 500×500 square size.
• true tells WordPress to crop the image to fit the exact dimensions. If you set this to false (or omit it), the image will be resized proportionally to fit within the dimensions, but may not be exact.

You can add multiple custom sizes by including multiple add_image_size lines:

add_image_size( ‘my-custom-size‘, 500, 500, true );
add_image_size( ‘homepage-featured‘, 1200, 600, true ); 
add_image_size( ‘index-thumbnail‘, 300, 200, false );

A few best practices to keep in mind:

• Prefix your size names with your theme or plugin name to avoid conflicts. For example, mytheme-custom-size instead of custom-size.
• Hook your add_image_size calls into the after_setup_theme action to ensure they run at the right point in the WordPress initialization process:

function mytheme_add_image_sizes() {
    add_image_size( ‘mytheme-custom-size‘, 500, 500, true );
}
add_action( ‘after_setup_theme‘, ‘mytheme_add_image_sizes‘ );

• Be mindful of how many sizes you‘re adding. Each custom size generates an additional file on the server, which can add up quickly. Aim for the minimum number that will meet your needs.

Cropping Modes Explained

The last parameter passed to add_image_size controls how WordPress crops the image. There are three main modes:

1. Hard crop (true) – The image will be cropped to the exact dimensions specified, even if it means cutting off part of the image. This is ideal for images that need to fit an exact container, like square thumbnails.

2. Soft crop (false) – The image will be resized proportionally to fit within the dimensions, without cropping. This means the resulting image may be smaller than the dimensions specified. For example, a 1000×800 image soft cropped to 500×500 would end up as 500×400.

3. Unconstrained height (9999) – Setting the height to 9999 tells WordPress to resize the width as specified but allow unlimited height. This is useful for images that need a specific width but can be any height, like full-width featured images.

Here‘s an example of registering a size for each mode:

add_image_size( ‘hard-crop‘, 300, 300, true ); // 300x300 square thumbnail
add_image_size( ‘soft-crop‘, 600, 400 ); // Proportional resize to fit 
add_image_size( ‘full-width‘, 1200, 9999 ); // 1200px wide, any height

The mode you choose will depend on your specific use case. When in doubt, soft crop is usually the safest bet to avoid losing important detail to cropping.

Regenerating Thumbnails

Here‘s the catch with custom image sizes: they only apply to new image uploads after the size has been registered. Any existing images in your media library won‘t have the new size generated automatically.

That means if you add a custom size and want to use it for featured images on existing posts, you‘ll need to regenerate your thumbnails. WordPress doesn‘t have a built-in way to do this, but there‘s a handy plugin for the job: Regenerate Thumbnails.

After installing and activating the plugin, head to Tools → Regenerate Thumbnails in your WordPress admin. You‘ll see a list of all your image sizes, including any custom ones:

Clicking "Regenerate Thumbnails for All X Attachments" will go through your media library and generate copies of each image in the new size. Depending on how many images you have, this may take a while, so it‘s best to run it during low-traffic hours.

A few tips for regenerating thumbnails:

• Back up your site before regenerating, just to be safe. The plugin won‘t delete any of your original files, but it‘s always good to have a backup.
• If you‘re on shared hosting, regenerating a large media library may hit memory limits or timeouts. Check with your host if you run into issues.
• Regenerating only applies the new sizes to existing images. If you‘ve changed the dimensions of an existing size (e.g. changing your "medium" size from 300×300 to 500×500), you‘ll need to use a plugin like Force Regenerate Thumbnails to update those as well.

Using Custom Sizes in Your Theme

Now that you‘ve registered your shiny new image size, how do you actually use it in your theme?

The easiest way is with the the_post_thumbnail template tag. This will display the featured image of a post in any registered size. Just pass the name of your custom size as a parameter:

the_post_thumbnail( ‘my-custom-size‘ );

This would output an img tag with the source set to the URL of the "my-custom-size" version of the post‘s featured image.

If you need more control over the markup, you can use wp_get_attachment_image_src to retrieve the URL and dimensions of a specific image size:

$image = wp_get_attachment_image_src( get_post_thumbnail_id(), ‘my-custom-size‘ );
echo ‘<img src="‘ . $image[0] . ‘" width="‘ . $image[1] . ‘" height="‘ . $image[2] . ‘" alt="‘ . get_the_title() . ‘">‘;

This would output a complete img tag with the source, width, height, and alt attributes filled in.

To use custom sizes for images within post content (as opposed to featured images), you‘ll need to enable them in the post editor. Add this snippet to your functions.php:

function my_custom_sizes_in_editor( $sizes ) {
    $sizes[‘my-custom-size‘] = ‘My Custom Size‘;
    return $sizes;
}
add_filter(‘image_size_names_choose‘, ‘my_custom_sizes_in_editor‘);

Now, when inserting an image in the post editor, your custom size will appear in the "Size" dropdown:

Image Size Best Practices

Before we wrap up, let‘s go over a few best practices to keep in mind when working with custom image sizes:

• Use descriptive names. Names like "small" or "custom-1" don‘t convey much meaning. Instead, use names that describe the image‘s purpose, like "homepage-featured" or "author-bio-thumbnail".

• Be consistent. Try to reuse sizes across your theme instead of registering new ones for every use case. This keeps your media library from getting cluttered with unnecessary duplicates.

• Optimize for performance. Only generate the sizes you actually need, and use the smallest size that will work for each context. Don‘t use a 2000px wide image if it‘s only ever displayed at 500px.

• Consider aspect ratio. If your theme relies on consistent aspect ratios for images (like 16:9 for video thumbnails), make sure to set your custom sizes to match. Mismatched aspect ratios can lead to awkward cropping.

• Use relative units. While custom sizes are defined in pixels, consider using relative units like percentages or vw in your CSS. This allows your images to scale responsively across different screen sizes.

• Leverage the srcset attribute. For even better performance, serve responsive images using the srcset attribute. This lets you specify multiple sizes for each image and serve the optimal one based on the user‘s screen size. Plugins like RICG Responsive Images can help automate this.

Plugins for Image Optimization

In addition to Regenerate Thumbnails, there are a few other plugins that can help optimize your images and streamline your workflow:

• Smush – Compresses and resizes images on upload, and can bulk optimize existing images. Also has lazy loading and WebP support.
• Imsanity – Automatically resizes huge images to more reasonable dimensions on upload. Great for preventing server bloat.
• Crop Thumbnails – Lets you manually crop individual thumbnails right in the media library. Useful for art-directed featured images.
• ImageKit.io Integration – Offloads image optimization and resizing to the ImageKit.io CDN. Offers real-time resizing, lazy loading, and automated optimization.

Custom Image Sizes FAQ

Still have questions? Here are answers to some common ones:

Can I use custom image sizes with the new WordPress block editor?
Yes! Custom sizes work just fine with the block editor. When adding an image block, you‘ll see your custom sizes in the "Image Size" panel in the block settings sidebar. You can also use custom sizes with featured image blocks and any custom blocks that support specifying an image size.

What happens if I change the dimensions of an existing custom size?
Changing the dimensions of an existing size won‘t automatically update previously uploaded images. You‘ll need to use a plugin like Force Regenerate Thumbnails to regenerate the updated size for existing images.

Can I delete a custom image size?
Yes, but be careful. If you remove a custom size that‘s being used in your theme, you‘ll end up with broken image links. It‘s best to only remove sizes if you‘re sure they‘re not being used anywhere. You can use a plugin like Media Cleaner to safely delete unused image sizes.

Do custom image sizes work with lazy loading?
Yes, custom sizes are just like any other image file and can be lazy loaded using a lazy loading plugin or browser native lazy loading. Just make sure to specify the dimensions of the image in the width and height attributes so the placeholder takes up the correct amount of space.

Wrapping Up

Whew, that was a lot to cover! But hopefully you now have a solid understanding of how WordPress handles image sizes and how you can optimize your media by adding your own custom dimensions.

To recap, custom image sizes allow you to:

• Serve perfectly sized images for every context on your site
• Speed up page loads by reducing unnecessary image data
• Ensure consistent styling and layout across your theme

By taking the time to register thoughtful custom sizes and diligently optimizing your images, you can give your users a faster, more polished experience and set your WordPress site up for success.

So go forth and resize! And if you have any tips or tricks of your own for working with WordPress images, share them in the comments below.