Image sizes in WordPress

A user asked me a few days ago how to get the image width and height of a custom-defined image size in WordPress. After searching through the WordPress source code, I couldn’t find a function that handled this. I suppose there really aren’t too many uses for it, but this user needed these values for a custom script, which at least intrigued me enough to write out a custom function to handle this.

In this tutorial, I’ll walk you through adding custom image sizes as well as getting these image sizes within your custom scripts.

This is not a complete tutorial on how images work in WordPress. I’ve previously written a tutorial on WordPress’ post image feature on my personal blog, but I didn’t delve into the details of adding custom sizes. I still highly recommend reading that tutorial if you want to look at few cool image features or learn more about how images work in WordPress.

How to create custom image sizes

I’m sure many of you are aware of how to add custom image sizes and use them, so please feel free to skip this section. I wanted to briefly cover this so that users new to adding image sizes can get the full picture.

WordPress comes pre-packaged with the thumbnail, medium, and large image sizes. When you upload an image using the WordPress media uploader, the image is resized and/or cropped to fit the proportions you’ve set under your media settings. Theme and plugin developers can also add custom sizes to accompany the built-in sizes.

To add a custom image size, you would use the add_image_size() function as shown in the following line of code.

add_image_size( $name, $width, $height, $crop );

The add_image_size() function takes in four parameters:

$name: Your unique name for this image size.

$width: The width (in pixels) for images of this size. The default is 0.

$height: The height (in pixels) for images of this size. The default is 0.

$crop: Whether to crop images of this size to the exact dimensions. The default is false.

Let’s suppose you wanted to add a custom image size called my-feature that was 600px by 200px and always cropped to the specific dimensions given. You would add the following code to your theme’s functions file or plugin file.

Getting the values of a custom image size

In the previous section of this tutorial, you learned how to add a custom image size. There may be a time when you need to get the width, height, or crop values of this custom image size. Since WordPress doesn’t have a function for this, I’ve written one for you.

It’s a simple function and takes in a single parameter of $name. Remember that custom image size you created in the previous section of this tutorial? my-feature would be the name of the image size you added. To get its values, you simply need to plug that name into the function.

$image_size = my_get_image_size( 'my-feature' );

The return value of the function will be an array of the values you initially set when using the add_image_size() function:

array(
'width' => 600,
'height' => 200,
'crop' => true
);

Suppose you needed to uses these values in a function called my_example_image_function() for whatever reason. Your function might look a little something like the following code.

As you can probably tell, I don’t really have any practical applications for this functionality. It’s just a cool little script that a user asked for that I thought I’d share. It’s up to you to figure out if you can make some use of it in your plugins or themes.

Getting WordPress image size values

The above functionality deals with custom image sizes. In most cases, your plugin or theme would already know these values because it’s setting them itself. However, plugins and themes don’t have control over the WordPress-packaged image sizes by default. These values are something that users set under their Media Settings screen in the admin.

The default WordPress images sizes are easy to retrieve. You just need a call to get_option() with the correct option name. Suppose you wanted to get the width of the thumbnail size the user has input. You’d use the following code.

$thumbnail_width = get_option( 'thumbnail_size_w' );

The available options are:

thumbnail_crop: Whether to crop the thumbnail to exact dimensions.

thumbnail_size_h: The height of the thumbnail.

thumbnail_size_w: The width of the thumbnail.

medium_size_h: The medium size height.

medium_size_w: The medium size width.

large_size_h: The large size height.

large_size_w: The large size width.

Don’t worry about extra database queries with this either. These options are auto-loaded on each page view, so you won’t run into issues in that area.

How can you use this?

As I’ve mentioned, I don’t have any projects or ideas where I want to use the get image size values functionality, at least not yet anyway. So, I thought I’d ask if you, our readers, have any ideas of where this could come in handy.

There is really no native function (that I know of, but I looked hard) that will get you dimensions, but there is get_intermediate_image_sizes() that will get you list of size names. Handy when you need to loop through sizes or filter out some sizes to make them invisible for core or other code.

As for usages – most complex thing I messed with this for so far is setting up custom crop area for specific size (I needed one size to crop upper third (face), rather than center of image).

I use custom image sizes *a lot* – on panos.org.uk for example there are six: hard-cropped square ones for post thumbnails & for the teaser boxes in the 3rd col, a box-resized one for the main image above each post, a hard-cropped fixed width & height one for the homepage carousel image, etc.

It works great for the customer as they only have to upload one image, set it to be the featured image, then it appears the correct size everywhere throughout the site.

Until now I’ve always used wp_get_attachment_image_src when I’ve needed to return the width & height, but your function looks very handy. Although of course it doesn’t return the exact values of individual box-resized images, only for hard-cropped ones.

wp_get_attachment_image_src() is definitely handy for getting an individual image’s width and height.

I think you may have misunderstood what I was asking about though. I wanted to know how people would use the custom image size values in their projects, not how they use custom image sizes. I’ll update the post to make that a bit more clear.

Actually, this could come in quite handy. Think of a form that allows multiple file uploads for a gallery website. The function would use the media_handle_upload to upload the file and assign it to a post, or simply upload it. Tutorial on that…

Basically you can get the information as you upload it for use elsewhere very easily. You could then use the devpress_register_image_sizes() to create the additional images past the default 4 (thumb, medium, large, default).

Though I wonder if WordPress media_handle_upload() would do this automatically? If you created 4 new image size definitions, would the media_handle_upload() automatically create the basic 4 plus the newly defined image dimensions or would it need to be dynamically done for each image on upload?

The thumbs system problem is that when you create new custom sizes they can’t be associated with a specific type of post.
So, each post save images that may never be used. It happened to me on a website, and solve it using different methods.

This may be slightly off-topic but I was wondering if anyone has solved this issue:

– Anyone figured out a way to grab the right image from this set you create in your theme based on the user’s device (say, on a browser the full-size image is loaded, but on mobile, a smaller image is produced)?

I know we can use CSS to scale images to their containers, but what about download times? I don’t feel good about scaling down a 1000-pixel-wide image on a phone even if it does look good. Why force the phone to download 100k of images when they could get an appropriately sized image instead?

I had a client that we were using featured thumbnails with, and we had an image size set for them, but images were not hard cropped – they could be smaller than the preferred image size.

In the theme we floated the featured image in the upper left of the article body.

Trouble was, they also wanted captions to show underneath the featured thumbnails. With the combination of floats and no width on the container (because the width was variable) we had problems where the thumbnail was smaller than our max-width but a long caption would max out the width of the container, making a silly looking amount of white space happen around the image.

We needed a width on the div container to stop the caption from stretching it. Here is what we ended up doing, with some extra math to account for a drop shadow on the image:

Hi Justin! My images size are set to what I want them, but aren’t displaying right in the blog. I want my images large size (I am a photographer and use my blog to showcase my work) but the images will only display in medium size even though all my settings for this seem to be right? Can you help?

Any chance there is a function to set the image names? like instated of imagename-150×150.png,imagename-300×300.png… it could be imagename-small, imagename-med, imagename-larg. Because then you could grab a different size image file depending on the size of the screen.

I use them in responsive web designs. Using the Picture.js polyfill the resized images are used depending on the size of the device the user is viewing the site on. For example, there is no reason a user should have to wait to see an image that is meant for viewing on a desktop computer when all he needs is a image big enough to view on his mobile device. Downloading a pre-resized 20k image is much faster than a universal 100k image. I know those are large sizes, but I thinking a use case for a photographer.

I was wandering… is there a way to update all our media in a wp-theme that I have just updated? I mean, I just changed the functions.php so I have new image sizes, but I have a lot of images already in my Media Folder, and those images are not resized because the resize magic occurs in the upload process.

¿Is there a way to upload all your images so they get resized as well and not only the new ones uploaded to your page?

By submitting a comment here you grant this site a perpetual license to reproduce your words and name/Web site in attribution.

Please use your real name or a pseudonym (i.e., pen name, alias, nom de plume) when commenting. If you add your site name, company name, or something completely random, I'll likely change it to whatever I want.