How to Add and Display a New Image Size in WordPress

WordPress 4.0 - Benny

WordPress comes out of the box with three image sizes built in – a thumbnail, a medium, and a large size.

Each theme developer will determine the exact dimensions of those three sizes. But typically, these three exist in some range between a thumbnail – 50 x 50 or 150 x 150; a medium size – maybe around 450 x 350; and a large image – bursting at the seams around 1024 x 800 or something (all sizes here are in pixels).

This means that for every image larger than the “large” size that you upload to the media area, WordPress will automatically create three additional sizes of that image. If your image is only 600 x 800, WordPress won’t create a “large” size of 1024 x 800 from it.

But assuming your uploaded image is larger than the “large”, you end up with four images – your original upload, plus the three images of thumbnail, medium, and large dimensions created by WordPress. WordPress can organize these into a nice filing system for you automatically.

You can view – and edit! – the dimensions for your WordPress installation by going to your Dashboard –> Settings –> Media
WordPress Media Settings

If you do update those settings, you can use a handy plugin like Regenerate Thumbnails to instruct WordPress to run through all of your media items and regenerate your images with the new dimensions. Pretty handy utility, say if you move into a new theme that uses different featured image widths or something.

What if those three dimensions are not enough for you? What if you want to add a fourth dimension?

You can add a new image dimension by making an edit to your functions.php file.

First, you want to tell WordPress that you want to add a new size. You do this by adding the add_image_size(); function to your functions.php file.

The add_image_size function accepts $name, $width, $height, and $crop parameters. Only $name is required. Like so:

// Add additional image sizes 
	add_image_size( 'homepage-thumb', 535, 350, true );

Here, I am telling WordPress to create a new image size with a name of "homepage-thumb", a width of 535 pixels, a height of 350 pixels, and yes, crop it if the proportions do not match the dimensions of the original image.

Likewise, we could write:

// Add additional image sizes 
	add_image_size( 'homepage-thumb', 535 );

The above would create the new image size with a width of 535 pixels but would not set any height restrictions.

And this code if handy if you want some control over the cropping axis position:

 // Hard crop left top
add_image_size( 'homepage-thumb', 535, 350, array( 'center', 'center' ) );

You can use 'left', 'center', or 'right', for the first position and 'top', 'center', or 'bottom' for the second position. Great!

There are several things you can do with this new image size, now that you've created it and given it a name. A handy thing to do is to make it available to the folks using the WordPress Dashboard.

To do that, you need to filter the image_size_names_choose function:

// Show new image size in admin are of media section
    add_filter( 'image_size_names_choose', 'yourTheme_custom_image_size' );

... and then load up your instructions:

function yourTheme_custom_image_size( $sizes ) {
    return array_merge( $sizes, array(
        'homepage-thumb' => __( 'Homepage Thumbnail' ),
    ) );

The whole code:

And that's how you add a new image dimension to your WordPress installation!