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.

add_action( 'init', 'my_register_image_sizes' );

function my_register_image_sizes() {

	add_image_size( 'my-feature', 600, 200, true );
}

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.

You can use the following function in your theme and plugin projects.

function my_get_image_size( $name ) {
	global $_wp_additional_image_sizes;

	if ( isset( $_wp_additional_image_sizes[$name] ) )
		return $_wp_additional_image_sizes[$name];

	return false;
}

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.

function my_example_image_function() {

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

	if ( !empty( $image_size ) ) {

		$width = $image_size['width'];

		$height = $image_size['height'];

		$crop = $image_size['crop'];
	}
}

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.

26 Responses

  1. Aaron D. Campbell
    Aaron D. Campbell Published |

    I use this for quite a few things. A recent example is the multi-site setup over at http://americanyouth.com where high school sports teams can sign up for their own site. Each one has a sponsors section to showcase their various sponsors. These are a custom post type, but they also make use of a custom image size that works with the sponsors archive layout:
    http://bashabearsfootball.com/sponsors/
    http://chandlerwolvesfootball.com/sponsors/
    http://libertylionsfootball.com/sponsors/

    Reply
  2. Bowe Frankema
    Bowe Frankema Published |

    I *think* this can be handy if you combine it with this code to output the image url: http://wpcoderz.com/get-post-thumbnail-url/

    Then when you have the height, width and the url of the image you could use that info for styling a div.

    Set the post thumbnail as a background-image for the div.
    Use the height and width properties to give the container the proper height and width.

    This could be used for a logo or something. Add a negative text-indent rule to the div, to hide the H1 site title, and voila..

    There’s probably easier ways to do this but it could be done right? :D

    Reply
  3. Avinash D'Souza
    Avinash D'Souza Published |

    Correct me if I’m wrong Justin, but the following code allows me to crop the post images to a specified width and height, right?

    add_action( ‘init’, ‘devpress_register_image_sizes’ );
    function devpress_register_image_sizes() {
    add_image_size( ‘devpress-feature’, 600, 200, true );
    }

    Reply
    1. Daniel R
      Daniel R Published |

      Yep if you set the attribute to true it will crop the image.

      Reply
  4. Rarst
    Rarst Published |

    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).

    Reply
  5. Simon
    Simon Published |

    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.

    Mark Jaquith’s post when 2.9 was released got me started on them: http://markjaquith.wordpress.com/2009/12/23/new-in-wordpress-2-9-post-thumbnail-images/

    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.

    Reply
  6. Neil Davidson
    Neil Davidson Published |

    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?

    Reply
  7. Jeremias Longo
    Jeremias Longo Published |

    Very good your stuff Justin!

    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.

    Do you know if that functionality will be added to Wordpress?

    Regards

    Reply
  8. Ryan Swarts
    Ryan Swarts Published |

    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?

    Reply
  9. Ronald
    Ronald Published |

    I have been looking for one or more articles that explain each tag line. This post helps me greatly in that manner.

    Reply
  10. Lillan
    Lillan Published |

    Hi!
    Do you really need the crop arg in WP 3.2? Isn’t it now implemented as a standard or am I wrong?

    Reply
  11. Lillan Backa
    Lillan Backa Published |

    hmmm….i just read about it somewhere, I’ll be back when i findthe link.

    Reply
  12. Bootscraper – Recycled Rubber and Coir Stripes Wire Brush Shag Doormat – 1'6" x 2'6" Size: 1'6" x 2'6" | Patio & Garden Supplies
  13. J. Hogue
    J. Hogue Published |

    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:

    if( has_post_thumbnail() ) {
    $image_meta = wp_get_attachment_image_src( get_post_thumbnail_id(), ‘thumbnail’ );
    echo “”;
    the_post_thumbnail( ‘article-size’ );
    echo “”.get_post( get_post_thumbnail_id() )->post_excerpt.””;
    echo “”;
    }

    So this is an example of needing to get the width of an image, even though there is a custom image size in place. It can’t always be relied on unless you are forcing images to take on that size.

    Reply
  14. Scott Fennell
    Scott Fennell Published |

    What’s the advantage of calling add_image_size in a hook, as opposed to just doing it without a hook?

    The advantage I see is to wrap it inside a pluggable function and allow a child theme to override the function.

    But is “init” sufficient? Wou;dn’t you need “admin_init” as well, so that wp knows to resize the image when uploaded?

    Reply
  15. SlotsMarvel
    SlotsMarvel Published |

    very helpful, thanks for this.
    Any chance that you know how to set the dimensions dynamically using a variable?

    Something like this

    add_image_size( ‘mythumb’, $custom_width, $custom_height, true );

    above doesn’t want to work, only if I enter the exact pixels values width numbers.

    Reply
  16. Lisa
    Lisa Published |

    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?

    Reply
  17. Sharon
    Sharon Published |

    Can you use them for specific images? Say I wanted vertical pictures to be the same height as horizontal pictures to achieve a more uniform look, could I do something like that?

    Reply
  18. Jeff H
    Jeff H Published |

    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.

    Reply
  19. Bryan Hinkle
    Bryan Hinkle Published |

    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.

    Reply

Leave a Reply

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.

css.php