A Guide to WordPress Image Crop Sizes

WordPress 3.9 has come out with a whole lot of extra power under the hood. An awesome new feature among many, is the added ability to now control crop position of images uploaded in WordPress – this is really slick!!

Before proceeding, a big thanks to Brad Touesnard who has made this awesome contribution that has now been included in WordPress core! I thought this will be a great opportunity to not only elaborate on how to take advantage of this new feature but to also run through and get a good grip on the entire scope of this function.

The Very Beginning – Adding or Customizing Image Sizes

By default WordPress generates 3x additional versions of your image. A ‘Thumbnail’, a ‘Medium’ and a ‘Large’ version. The original image size uploaded is referred to as the ‘Full’ version.

Customizing the Defaults

You can overwrite the default values of each of these crop sizes quite easily. You can either go to your WordPress Dashboard, Settings >> Media and change the values there or you can do so via your theme or plugin functions file like this:

update_option('thumbnail_size_w', 250);
update_option('thumbnail_size_h', 250);
update_option('thumbnail_crop', 1);

Adding Additional Sizes

You can quickly and easily place this function in your theme or plugin functions file:

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

It would end up looking something like this:

add_image_size( 'homepage-thumb', 250, 250, true );

Tip: Remember to give each additional image size its own unique name ;-).

Everything you need to know can be found via the WordPress Codex.

Some WordPress 3.9+ Magic – Controlling the Crop Position

The parameter $crop was previously just a Boolean value, true or false. So Either a soft proportional crop or a hard crop if set to true (keep reading further down to see the difference between a hard and soft crop). However now you can use an array to specify positioning of the crop area, (x_crop_position, y_crop_position). I like images cropped from the center, so for example your function could look like this now:

add_image_size( 'homepage-thumb', 250, 250, array( 'center', 'center' ) );

The $crop parameter still accepts true/false values and according to Brad, is fully backwards compatible. The syntax is identical to that of the CSS background-position property, so its familiar to both designers and developers but here they are in any case for the sake of clarity.

left top
left center
left bottom
right top
right center
right bottom
center top
center center
center bottom

So I’ve Got it Cropped, Now How Do I Use It?

The great news… its exactly the same!! For a full breakdown, as always look at the WordPress Codex. Here is a reminder in any case. To call this custom image in your theme or plugin. In the example we have been using, here is how:

the_post_thumbnail('homepage-thumb');

or…

wp_get_attachment_url( get_post_thumbnail_id($post->ID, 'homepage-thumb') );

But What About All My Existing Images?

As you are likely aware, the crop sizes are cycled through and generated at the time of your upload. This now means that after making use of this new feature by adding our custom cropping position or changing/adding a new crop size we are now left with what was generated at the time of upload and none of these new image versions are available to us, not cool!

Aaah but wait.. Fortunately their are plenty smart and awesome people around in the WordPress community to save the day, here is the regenerate thumbnails plugin. This plugin has been around for a long time, its fantastic! It will cycle through all your existing uploaded images and regenerate all of the new image sizes you have added or customized. Woohooo problem solved 🙂

Hard Vs. Soft Crop – You Decided

Hard Crop

The image will be scaled and then cropped to the exact dimensions you have specified. Depending on the proportion of the image in relation to the crop size, the chances are the image will always be cut off.

Soft Crop

A soft crop will never cut off any of the image, it will scale the image down until it fits within the dimensions specified, maintaining its original aspect ratio.

Something Worth Knowing…

In the event that any dimension of the uploaded image, (width or height) is smaller than that of the set crop size, it will be skipped and a version for that size will not be made! WordPress will cycle through all the set image sizes and only create the versions of those images that are bigger than that of the version it is trying to generate. In such a case, when an image is being retrieved within your theme or plugin and does not exist, it will default to the original, ‘Full’ image as a fallback.

Enjoy implementing this great new feature on your themes and plugins. Time to go kick some ass and crop some images 🙂