New in WordPress 2.9: Post Thumbnail Images

Many WordPress themes, especially those with “magazine-like” layouts, use an image to represent each post. It might just be on the front page. It might be alone, or alongside an excerpt. Until now, there was no standardized way to do this. Many themes would require you to tediously enter a Custom Field with the value being the URL you wanted to use. Often you had to do cropping yourself. With WordPress 2.9, theme authors can easily enable Post Thumbnail selection UI and call those image using simple template tags.

First, in the theme’s functions.php, declare that your theme supports this feature. This will enable the UI in the WP Admin.

add_theme_support( 'post-thumbnails' );

That will enable Post Thumbnail UI for both Post and Page content types. If you’d only like to add it to one, you can do it like this:

add_theme_support( 'post-thumbnails', array( 'post' ) ); // Add it for posts
add_theme_support( 'post-thumbnails', array( 'page' ) ); // Add it for pages

Simply remove the one you don’t want to support.

Next, you should specify the dimensions of your post thumbnails. You have two options here: box-resizing and hard-cropping. Box resizing shrinks an image proportionally (that is, without distorting it), until it fits inside the “box” you’ve specified with your width and height parameters. For example, a 100×50 image in a 50×50 box would be resized to 50×25. The benefit here is that the entire image shows. The downside is that the image produced isn’t always the same size. Sometimes it will be width-limited, and sometimes it will be height-limited. If you’d like to limit images to a certain width, but don’t care how tall they are, you can specify your width and then specify a height of 9999 or something ridiculously large that will never be hit.

set_post_thumbnail_size( 50, 50 ); // 50 pixels wide by 50 pixels tall, box resize mode

Your second option is hard-cropping. In this mode, the image is cropped to match the target aspect ratio, and is then shrunk to fit in the specified dimensions exactly. The benefit is that you get what you ask for. If you ask for a 50×50 thumbnail, you get a 50×50 thumbnail. The downside is that your image will be cropped (either from the sides, or from the top and bottom) to fit the target aspect ratio, and that part of the image won’t show up in the thumbnail.

set_post_thumbnail_size( 50, 50, true ); // 50 pixels wide by 50 pixels tall, hard crop mode

Now, you can make use of the template functions to display these images in the theme. These functions should be used in the loop.

has_post_thumbnail() returns true/false and indicates whether the current post has a manually-chosen Post Thumbnail (in the loop):

<?php
if ( has_post_thumbnail() ) {
	// the current post has a thumbnail
} else {
	// the current post lacks a thumbnail
}
?>

the_post_thumbnail() outputs the Post Thumbnail, if it exists (in the loop):

<?php the_post_thumbnail(); ?>

Those are the basics. How about some advanced stuff?

What if you want to use a small 50×50 hard-cropped image for the home page, but want to use a 400 pixel-wide (unlimited height) image on the post’s permalink page? You’re in luck. You can specify additional custom sizes! Here’s the code:

functions.php

add_theme_support( 'post-thumbnails' );
set_post_thumbnail_size( 50, 50, true ); // Normal post thumbnails
add_image_size( 'single-post-thumbnail', 400, 9999 ); // Permalink thumbnail size

home.php or index.php, depending on your theme structure (in the loop):

<?php the_post_thumbnail(); ?>

single.php (in the loop):

<?php the_post_thumbnail( 'single-post-thumbnail' ); ?>

That’s it! set_post_thumbnail_size() just calls add_image_size( 'post-thumbnail' ) — the default Post Thumbnail “handle.” But as you can see, you can add additional ones by calling add_image_size( $handle, $width, $height, {$hard_crop_switch} );, and then you use that new size by passing the handle to the_post_thumbnail( $handle );

If you want your theme to support earlier versions of WordPress, you’ll have to use function_exists() to keep from calling these new functions in those versions. I’ve omitted that code to keep these examples as simple as possible. Here would be the functions.php example with the wrapper code:

if ( function_exists( 'add_theme_support' ) ) { // Added in 2.9
	add_theme_support( 'post-thumbnails' );
	set_post_thumbnail_size( 50, 50, true ); // Normal post thumbnails
	add_image_size( 'single-post-thumbnail', 400, 9999 ); // Permalink thumbnail size
}

There is one caveat for this feature in WordPress 2.9 — it only works fully for new image uploads. We can’t yet resize images on the fly, although I’m strongly considering it for a future version. If you call the template functions on a post that has a Post Thumbnail that was uploaded prior to your theme having declared the new sizes, you won’t be able to do hard-cropping, and the box-resize will be done in the browser. As a temporary solution, Viper007Bond has a great plugin that will go back and create missing image sizes for you: Regenerate Thumbnails.

I’m looking forward to see what kinds of sites you can build with this feature!