Steve Taylor photo

Planning WordPress image sizes

On larger projects, designs that need to be turned into a custom WordPress theme can have a wide array of image sizes. I’m currently working on such a project, and I thought I’d share a few things that might help others working in a similar situation. My aim is to contribute to a better understanding of how WordPress currently handles image sizing, how understanding this can potentially feed into the design process, and how WordPress developers can respond to design requirements while not making life too confusing for the client’s content editors.

WordPress image sizes

WordPress has three built-in size settings for uploaded images to be automatically resized to—thumbnail, medium and large—which are configured via the Media Settings screen.

In addition, if the theme supports it (via add_theme_support('post-thumbnails')), post thumbnails potentially provide another size. “Post thumbnail” is a bit of a misnomer. The metabox on post edit screens these days reads “Featured image”, which is better—but the code for this feature retains “post thumbnail”. This field is basically a way of foregrounding a particular image associated with a post or page. All images uploaded via a post’s edit screen are “attached” to that post, so if the theme has a space at the top of the post template for a main image to be placed there automatically, which image to use? This is where the featured image comes in. “Post thumbnail” is a little misleading because the size of this image may be quite large. The featured image size in the default Twenty Eleven theme is 1000px x 288px—hardly a thumbnail! Anyway, the default size for post thumbnails can be set to use one of the three built-in sizes, or defined with new dimensions.

On top of this, developers are free to as as many more additional custom images sizes as they want with add_image_size().

Note that by default, only the three built-in sizes are available for editors to insert into posts and pages. To allow custom image sizes to be inserted manually like this, a plugin is available.


An important aspect of planning image sizes for your project is understanding how WordPress handles cropping.

Firstly, using the built-in image editor, you can crop images you’ve uploaded. You can crop the built-in thumbnail size independently of the other sizes, but that’s the limit to cropping freedom in WordPress. There’s a plugin called Post Thumbnail Editor that seems to address this limitation, but I’ve not managed to get it working properly. The basic issue is that the parts of the core code that deal with cropping the thumbnail separately from the other sizes don’t have any useful hooks through which developers could properly implement this feature.

In any case, when you define a custom image size, a cropping parameter is set to true (“hard” cropping) or false (“soft”, proportional cropping—the default). The best way to understand what this means is to look at some examples.

Basically, “soft” cropping isn’t really cropping. It will resize the image to the given dimensions, keeping it as large as possible while also retaining the image proportions. So if the uploaded image doesn’t match the image size’s proportions, and the image is placed, centered, in a box matching the defined image size, you’ll get some blank space above and below or to the sides of the image.

“Hard” cropping, on the other hand, may actually crop. It will crop the image so it matches the defined image size’s proportions, then resize it to be the exact size given. Cropping is done from the center, so if the uploaded image is a different proportion, you either lose a bit from the top and bottom, or from the sides.


Soft crop
Whole image kept, in original proportions, but the resized version may not fill the defined image size box
Hard crop
Resized version fits the defined image size box exactly, but parts of image may be lost in cropping

Brad Touesnard has come up with some code that lets you define where the cropping is done from, e.g. from the bottom right instead of from the default centre. The code has been submitted as a core patch, but its target milestone was shifted from 3.4 to “future release”. So even though some media improvements are slated for 3.5, this may not be one of them—let alone individual image size cropping.

In sum, I think for planning image size settings, these rules of thumb can be taken from how WordPress handles cropping:

  1. Image sizes that are to be used for things like logos and portraits, where cropping may “disfigure” the image significantly, should be set to “soft” cropping.
  2. If an image size is to be used in a place in the design that has distinct boundaries, you should probably set cropping to “hard”. This will avoid unsightly gaps in the designed layout.
  3. If in doubt, the default “soft” is best, to keep the whole image.
  4. If “hard” cropping has to be used for layout purposes, but cropping is still important, it may be worth stressing to the client that these images should be cropped to the right size before uploading, if possible.

Planning image sizes

For the current project I’m working on, I created a spreadsheet to get my head around things. You can download it and use it as a template for planning your own custom theme projects:


The upper section of the spreadsheet details all the various image sizes used in the PSDs supplied to me, and the lower section is my plan for the corresponding image sizes defined in WordPress. Some of the details are specific to the project, but they should give you a general idea of my approach. Here are some other notes:

  • The Proportion column is a simple formula that divides the width by the height.
  • Allowed height variation is a rough guide to how flexible the design is in terms of the image height.
  • Source indicates where the image is coming from—usually the page itself, or from a target page. For instance, a listing page will source the thumbnail for each item listed from that item’s featured image.
  • WP size maps the sizes defined in the lower section of the sheet to each size in the design.

So, to plan your own project you can:

  1. Delete all the “Location” and “custom size” rows!
  2. Start populating the “Location” rows with the sizes from the design you’re working with.
  3. When that’s done, look at the Width, Height and Proportion columns. See what overlaps there are.
  4. Then start changing the built-in size settings and adding custom image sizes, and mapping them to the design location sizes.


Proportion is important for images that are used in different locations as different sizes. For instance, you might want to place the featured image from a certain post type in the single post template at quite a large size, and use the same image as a thumbnail on that post type’s listing page. Ideally, these two location’s sizes would have the same proportion, so the same image can be used in different sizes without any cropping.

Variable height

Width is the most important dimension, and where possible design locations with the same width should be assigned to the same image size. Height is usually the dimension that is most flexible in web page layouts. I always bear in mind that it’s possible to do minor cropping in the browser, by setting CSS overflow: hidden for the image’s containing element, and letting any overhang be hidden.

For instance, the “Home carousel – single cell” image in the design is 226 x 188px, and the “Team detail” image is 226 x 179px. This is a small variation, and the Team detail image has good scope for height variance. So rather than defining two separate image sizes, I defined one at 226 x 188px, with a hard crop. This works for the carousel single cell image. And if we really have to limit the team detail image to 179px high, we can do “in-browser” cropping and lose a few pixels off the bottom.

Also bear in mind that you can define a custom image size with the height set to 0—which basically means the height is irrelevant. That image size will just be the specified width, and the proportional height will be kept.

Feeding back to design

If you design as well as develop your projects, you can obviously save a lot of time by planning your designs with all the WordPress constraints in mind. If designs are supplied to you, you may still be able to improve the process by feeding back useful information about how you work to the designer.

Obviously there should be freedom in the design process to do layouts with too many technical constraints. But often the variations in image sizes that necessitate a large number of custom image sizes aren’t bringing in huge aesthetic gains, and could be whittled down to make development simpler. It’s a trade-off as ever, and communication is the key.

While I’m too involved in the development right now to speak authoritatively on the design end of things, I think the most important take-aways for designers here are:

  • Where possible, use the same proportions for featured images on detail pages as for corresponding thumbnails on listing pages.
  • Try to keep a running list of the sizes of the images in your designs. Whenever you create a new image location in a design, refer back to this list and see if there’s anything pretty close to what you need. If there is, consider using that size and fitting the bits you’ve not designed yet around that.

Obviously the use of a layout grid could improve this process dramatically—though there will always be necessary exceptions, and for developers it’s good to have a variety of tricks in your bag.

If you end up with what seems like a large number of image sizes, don’t get too hung up on it. All those versions of each image that gets uploaded can feel like clutter in the uploads folder, and certainly consider disk space if you’ve got a small hosting package and a large number of large image sizes. But it’s an ongoing process of learning how to balance between design requirements, development constraints, and making the editorial process as simple as possible for clients.

Hopefully these thoughts are useful. Do let me know your own experiences and thoughts—I might distill and develop this into a more formal guide in the future.