Thumbnails show up in all sorts of places in WordPress — the homepage post list, category and tag archive pages, search results, and, depending on your theme, widgets and other sidebar elements too.
WordPress bakes some basic thumbnail options into the admin dashboard, but you can also define additional custom sizes. Here’s a guide to doing that.
When you define thumbnail sizes, you also choose how the image gets cropped to fit. Maybe you want square thumbnails, or wide letterbox crops, or you want to make sure the full image always shows. This guide covers the crop modes available in WordPress, what each one does, and when you’d use it.
For the examples below, I’m using a simple labeled graphic so the cropping behavior is easy to see. Because landscape and portrait images aren’t always handled the same way, I’ve included both orientations throughout. Both originals were uploaded as 1024×600px JPEGs.
Soft crop
A soft crop is a proportional resize — what most people would think of as a simple resize rather than a crop at all. The entire image fits inside the dimensions you specify without any pixels being cut off. If the image’s aspect ratio doesn’t match the box, you’ll get blank space on two sides.
In the WordPress dashboard under Settings > Media, the soft crop is what you get when you leave the “Crop thumbnail to exact dimensions” checkbox unchecked.
In functions.php, you specify a soft crop with FALSE as the fourth argument:
add_image_size( 'wordpress-thumbnail', 200, 200, FALSE );Result with a landscape image:
And with a portrait image:
For more on add_image_size and how to use it in functions.php, see How to Resize WordPress Thumbnails.
Hard crop
A hard crop fills the exact dimensions you specify and trims whatever doesn’t fit. If you want uniform square thumbnails from a mix of landscape and portrait images, this is how you get them. The virtue is consistency — every thumbnail comes out the same shape, which makes for a tidier layout.
By default, the hard crop centers on the image and trims equally from both sides of whichever dimension is too long. For a landscape image being cropped to a square, it trims equally from left and right. For a portrait image, it trims equally from top and bottom.
In the dashboard under Settings > Media, checking “Crop thumbnail to exact dimensions” sets a hard crop.
In functions.php, you specify it with TRUE:
add_image_size( 'wordpress-thumbnail', 200, 200, TRUE );Result with a landscape image:
And with a portrait image:
Array crops
The default hard crop always focuses on the center. But what if the subject of most of your images is off-center — say, near the top of the frame? Array crops let you control where the crop anchors by specifying an x-axis position (left, center, right) and a y-axis position (top, center, bottom).
There’s an important quirk to understand before working with these: you might expect nine distinct crop positions (top-left corner, bottom-right corner, etc.), but that’s not how WordPress handles it. Because WordPress always fills at least one full dimension first and then trims the other, only one axis is actually relevant at a time — and which axis depends on the image’s orientation.
For a landscape (wider-than-tall) image being cropped to a square, the image is already tall enough — it’s the width that needs trimming. So the x-axis (left/center/right) controls which part of the image is kept, and the y-axis instruction is effectively ignored.
For a portrait (taller-than-wide) image being cropped to a square, the image is already wide enough — it’s the height that needs trimming. So the y-axis (top/center/bottom) controls which part is kept, and the x-axis instruction is ignored.
In practice, this means the nine position combinations collapse into three distinct behaviors per orientation. The examples below illustrate this for each combination.
Array crops are only available via functions.php — they can’t be set through the WordPress dashboard. More on that here.
Top left
add_image_size( 'wordpress-thumbnail', 200, 200, array( 'left', 'top' ) );Landscape image: the x-axis applies, so it takes the left side:
Portrait image: the y-axis applies, so it takes the top:
Top center
add_image_size( 'wordpress-thumbnail', 200, 200, array( 'center', 'top' ) );Landscape image: center on the x-axis, same result as the default hard crop:
Portrait image: top on the y-axis:
Top right
add_image_size( 'wordpress-thumbnail', 200, 200, array( 'right', 'top' ) );Landscape image: right on the x-axis:
Portrait image: top on the y-axis:
Center left
add_image_size( 'wordpress-thumbnail', 200, 200, array( 'left', 'center' ) );Landscape image: left on the x-axis:
Portrait image: center on the y-axis, same as the default hard crop:
Center
Both axes set to center — identical to the default hard crop in both orientations. Included here for completeness, but there’s no practical reason to use it over TRUE.
add_image_size( 'wordpress-thumbnail', 200, 200, array( 'center', 'center' ) );Center right
add_image_size( 'wordpress-thumbnail', 200, 200, array( 'right', 'center' ) );Landscape image: right on the x-axis:
Portrait image: center on the y-axis, same as the default hard crop:
Bottom left
add_image_size( 'wordpress-thumbnail', 200, 200, array( 'left', 'bottom' ) );Landscape image: left on the x-axis:
Portrait image: bottom on the y-axis:
Bottom center
add_image_size( 'wordpress-thumbnail', 200, 200, array( 'center', 'bottom' ) );Landscape image: center on the x-axis, same as the default hard crop:
Portrait image: bottom on the y-axis:
Bottom right
add_image_size( 'wordpress-thumbnail', 200, 200, array( 'right', 'bottom' ) );Landscape image: right on the x-axis:
Portrait image: bottom on the y-axis:
Adding to your functions.php file
The add_image_size() calls need to live inside a function that’s hooked to after_setup_theme. Dropping them in bare as top-level code can work in some environments but isn’t reliable. The correct pattern looks like this:
function my_custom_image_sizes() {
add_image_size( 'after-post', 160, 160, TRUE );
add_image_size( 'home-bottom', 200, 200, TRUE );
}
add_action( 'after_setup_theme', 'my_custom_image_sizes' );That goes in your active theme’s functions.php file. A few things worth knowing before you edit it:
Back up first. A syntax error in functions.php produces a blank white screen that takes your site down until you restore the previous version. Keep a copy you can put back. The most common culprit is curly quotes vs. straight quotes — if you’re copying code from a word processor or a web page, make sure the quotes are straight (' and ") and not the typographic curly versions.
Use a child theme. functions.php lives in your theme directory, which means a theme update overwrites it. If you add image sizes to the parent theme’s functions.php, you’ll lose them when the theme updates. The right approach is to create a child theme and make your edits there — child theme files survive parent theme updates.
Prefer a code snippets plugin. If you’d rather not touch functions.php directly, the Code Snippets plugin is the standard solution. I also like FluentSnippets. Both are available in the WordPress Plugin Repository. They let you add PHP snippets through the dashboard, keeps them separate from your theme entirely, and survives theme changes and updates without any extra effort.
A few things to watch out for
You can’t have two different crops at the same pixel dimensions. WordPress generates thumbnail filenames based purely on dimensions — photo-200x200.jpg — with nothing in the filename indicating which crop mode was used. If you register two image sizes at 200×200 with different crop settings, WordPress will only generate one file and the second registration silently wins. If you genuinely need two differently-cropped versions at the same size, you’ll need to use slightly different dimensions to force distinct filenames.
New image sizes only apply to newly uploaded images. WordPress generates thumbnail variants at upload time. If you add a new image size after images are already in your media library, existing images won’t have that size generated automatically. You’ll need a plugin like Regenerate Thumbnails to retroactively create the new size for existing uploads.
If the crop keeps cutting off faces, the Theia Smart Thumbnails plugin adds face detection to the cropping process, automatically shifting the crop anchor to keep faces in frame regardless of which crop mode you’ve specified.
