We’re continuing our Explaining WordPress series with a look at the post thumbnail. What exactly is the post thumbnail? It’s the featured image for a specific post that can be displayed within the theme and can be cropped to multiple sizes on upload.
the_post_thumbnail( $size, $attr );
The most common way to display the featured image for a post is to call the_post_thumbnail() within The Loop for the post. the_post_thumbnail() takes two arguments $size and $attr.
$size can be used to specify a predefined size or an array containing a width and height value in pixels. By default your $sizes could be ’thumbnail’, ‘medium’, ‘large’, and ‘full’. Which can be set in the Media Screen. You can also create custom image sizes using the add_image_size( $name, $width, $height, $crop ) function which we’ll get into shortly.
$attr lets you set an attribute / value pair to add classes or alt text to images.
Let’s add a new image size before we show examples of pulling in the_post_thumbnail();
add_image_size( $name, $width, $height, $crop );
$name is a required string naming the new image size. You’ll use this string when calling the_posh_thumbnail(’name’); in your theme.
$width is an optional field, but obviously is used to set the width of the thumbnail in pixels. Defaults to 0 and you can set this to 9999 to resize based on the $height value instead.
$height is like width, but for height. Set your height in pixels here.
$crop can be a bit confusing. There’s 3 options.
- false performs a soft proportional “crop”. Really this resizes the image proportionally and doesn’t crop off anything.
- true performs a hard crop. This will crop the image to exact pixels specified in the width and height.
- array lets you specify the positioning of the crop area (x_crop_position, y_crop_position). Using this we could set an image to always crop from the top left corner instead of the center. If for some reason you wanted to do that.
For more of an explanation on cropping modes check out this article by David Tan.
So we’ll create a new thumbnail that crops to 500 x 400 instead of the default perfect squares.
add_image_size('thumb-500-400', 500, 400, true);
One thing to keep in mind with image sizes is that if you set a thumbnail size to crop to 500 x 400 and then upload an image that is 500 x 380 it won’t crop to 500 x 400. In order to crop the uploaded image must be bigger than both dimensions in the image size.
Using in the theme
All you’ve got to do to pull in your featured image in your theme is use the the_post_thumbnail() function. Here’s some examples of the sizes we covered.
the_post_thumbnail(); // Returns the default thumbnail size from your Media Screen settings
the_post_thumbnail('thumbnail'); // Again returns the default thumbnail size
the_post_thumbnail('medium'); // Returns the medium resolution image
the_post_thumbnail('large'); // Returns the large resolution image
the_post_thumbnail('full'); // Returns the full resolution (original image)
the_post_thumbnail('thumb-500-400') // Returns our custom image size of 500 x 400
You can also wrap the the_post_thumbnail() call in an if statement checking for the has_post_thumbnail() function to see if a post has a featured image set before trying to return a thumbnail that may not exist. that would look like this:
<?php
if ( has_post_thumbnail() ) {
the_post_thumbnail();
}
?>
has_post_thumbnail() takes only one argument. The $post_id. So don’t pass it your thumbnail names.
That does it for this edition of Explaining WordPress. There’s plenty more you can do with post thumbnails so check out the Codex.
