WordPress.org

Ready to get started?Download WordPress

Codex

Attention Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Post Thumbnails

Post Thumbnails is a theme feature introduced with Version 2.9. It was quickly changed to Featured Images with Version 3.0. Post Thumbnail, now Featured Image, is an image that is chosen as the representative image for Posts, Pages or Custom Post Types. The display of this image is up to the theme. This is especially useful for "magazine-style" themes where each post has an image.

Enabling Support for Post Thumbnails

Themes have to declare their support for post thumbnails before the interface for assigning these images will appear on the Edit Post and Edit Page screens. They do this by putting the following in their functions.php file:

add_theme_support( 'post-thumbnails' ); 

Note: To enable Post Thumbnails only for specific post types see add_theme_support()

Setting a Post Thumbnail

If your theme was successful in adding support for Post Thumbnails the "Featured Image" metabox will be visible on the on the Edit Post and Edit Page screens. If it isn't, make sure "Featured Image" is enabled in the screen options on the top right.

Featured Image Metabox

Featured Image metabox

After clicking the "Set featured image" link follow the same steps as inserting images in Posts and Pages. Once you have selected the featured image and determined the image settings, click on the blue "Set featured image" button, to set it as the featured image for your page or post.

"Set featured image" button

"Set featured image" button

Function Reference

Template Tags
Other Functions

Examples

Default Usage

// check if the post has a Post Thumbnail assigned to it.
if ( has_post_thumbnail() ) {
	the_post_thumbnail();
} 
the_content();

Note: To return the Post Thumbnail for use in your PHP code instead of displaying it, use: get_the_post_thumbnail()

Linking to Post or Larger Image

To link the Post Thumbnail to the Post permalink or a larger image see the examples in the_post_thumbnail()

Thumbnail Sizes

The default image sizes of WordPress are "thumbnail" (and its "post-thumbnail" and "thumb" aliases), "medium", "large" and "full" (the image you uploaded). These image sizes can be configured in the WordPress Administration Media panel under Settings > Media. This is how you use these default sizes with the_post_thumbnail():

the_post_thumbnail();                  // without parameter -> Thumbnail

the_post_thumbnail('thumbnail');       // Thumbnail (default 150px x 150px max)
the_post_thumbnail('medium');          // Medium resolution (default 300px x 300px max)
the_post_thumbnail('large');           // Large resolution (default 640px x 640px max)
the_post_thumbnail('full');            // Original image resolution (unmodified)

the_post_thumbnail( array(100,100) );  // Other resolutions

Set the Post Thumbnail Size

To be used in the current Theme's functions.php file.

Set the default Post Thumbnail size by resizing the image proportionally (that is, without distorting it):

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

Set the default Post Thumbnail size by cropping the image (either from the sides, or from the top and bottom):

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

Add New Post Thumbnail Sizes

Example of a new Post Thumbnail size named "category-thumb".

To be used in the current Theme's functions.php file.

add_image_size( 'category-thumb', 300, 9999 ); //300 pixels wide (and unlimited height)

Here is an example of how to use this new Post Thumbnail size in theme template files.

<?php the_post_thumbnail( 'category-thumb' ); ?>

Example of functions.php

if ( function_exists( 'add_theme_support' ) ) { 
add_theme_support( 'post-thumbnails' );
set_post_thumbnail_size( 150, 150, true ); // default Post Thumbnail dimensions (cropped)

// additional image sizes
// delete the next line if you do not need additional image sizes
add_image_size( 'category-thumb', 300, 9999 ); //300 pixels wide (and unlimited height)
}

Styling Post Thumbnails

Post Thumbnails are given a class "wp-post-image". They also get a class depending on the size of the thumbnail being displayed You can style the output with these CSS selectors:

img.wp-post-image
img.attachment-thumbnail
img.attachment-medium
img.attachment-large
img.attachment-full

You can also give Post Thumbnails their own class.
Display the Post Thumbnail with a class "alignleft":

<?php the_post_thumbnail('thumbnail', array('class' => 'alignleft')); ?>

Source File

External Resources

Related

Post Thumbnails: has_post_thumbnail(), the_post_thumbnail(), get_post_thumbnail_id(), get_the_post_thumbnail(), add_image_size(), set_post_thumbnail_size()

Theme Support: add_theme_support(), remove_theme_support(), current_theme_supports()
Features: sidebar, menus, post-formats, post-thumbnails, custom-background, custom-header, automatic-feed-links, content_width, editor-style, html5