How to display WordPress featured image tutorial

Since the very beginig WordPress, the featured image was one of the main elements of each post and page. It was mainly used as a thumbnail photo in post feeds such as categories, archives or search results. Nowadays there’s a wide variety of application for it, depending of the developer’s imagination and ideas. This tutorial will show you how to display WordPress featured image anywhere within the web site template.

Initial reqirements to display WordPress featured image

In order to display the WordPress featured image, firstly we have to meet a couple of preconditions:

• the theme must support featured images *
• posts must have added featured images

* Almost all WordPress themes support featured images. In case the theme you are working on doesn’t or you are developing a new one, you can enable featured images by adding add_theme_support( ‘post-thumbnails’ ); to your functions.php file.

WordPress Featured image sizes

Before you learn how to display WordPress featured image inside the template, firstly we have to understand what happens when we add a featured image to a post or page.

When you set the featured image for a certain post or page, WordPress creates a couple of versions of the image in different dimensions. Depending on the theme usually WordPress creates a thumbnail, a medium sized image and a large size image. This allows displaying different images sizes for different purposes. That way you can display the thumbnail in post archives and categories, and a medium or large image within your post.

For example, in the Twenty Nineteen theme, featured image sizes are the following:

• Thumbnail: 150×150 px (with square crop option)
• Medium size: 300×300 px
• Large size: 1024x1024px

This values can be changed in the Dashboard menu Settings/Media. The values are maximum dimensions. For landscape images maximum width value is used and for portrait images maximum height is used.

Featured image dimensions can be customized inside the WordPress Dashboard’s Media Settings.

Default Featured image size

Apart from the customizable featured image sizes, WordPress themes have a default maximum featured image size. The default dimensions are defined in the functions.php file. It’s purpose is to prevent too large images to be displayed as featured images.

For example, lets’ say you upload a 4000×3000 pixels photo and set it as a featured image. WordPress will display it’s default image size copy of the photo. This happens only if you haven’t previously defined a custom featured image size to display within the template.

To change the default featured image size for your theme, locate the function set_post_thumbnail_size inside the functions.php file and adjust the values to your needs. For example, the WordPress theme Twenty Nineteen has the default featured image set to 1568 pixels maximum width and 9999 pixels maximum height. In this case the function looks like this: set_post_thumbnail_size( 1568, 9999 );

Display WordPress featured image inside a template

Now that we enabled support for featured images, defined the image sizes and added a featured image to a post, its it time to display it in the template. Therefore, we must add a function that calls the featured image to a template file.

In our example, we’ll display the featured image inside a single post template.Let’s place it between the post title and the content. Firstly we have to locate the code within the template files which displays the post content. Usually, the code can be located right inside the single.php file. In some cases it can be in other files called from the single.php file. In our case,(Twenty Nineteen theme), we find the code inside the content-single.php file located in the /template-parts/content/ folder.

We’ll place the function the_post_thumbnail(); that displays the featured image between the closing entry-header header tag and the opening entry-content div. This position may slightly vary from theme to theme.

This is the basic PHP function to display WordPress featured image:

<?php the_post_thumbnail();  ?>

Adding this piece of code to your template file will display the post featured image on the desired position. Since the function has no arguments inside the brackets, the featured image will be displayed in the theme default dimensions. As mentioned before, we define the default dimensions in the functions.php file.

Control over displaying WordPress featured images

Now, let’s expand the function a bit for more control over the featured image display:

<?php 
if ( has_post_thumbnail() ) {
echo '<div class="featured-image">';
the_post_thumbnail('medium');
echo '</div>'; }
?>

In the code snippet above, firstly we wrapped the featured image with a div element. That will give us more control when styling with CSS later. Secondly, we added an if statement to check if the post has a featured image set. In case it doesn’t the whole block won’t be displayed at all. Finally, we defined the dimensions of the featured image by adding the ‘medium’ argument to the the_post_thumbnail(); function. In this case, the value of the medium featured image set in Dashboard Media Settings will be used.

All arguments that can be used in the the_post_thumbnail function:

• the_post_thumbnail(); the function without argument will display the featured photo in default dimensions defined in functions.php
• the_post_thumbnail( ‘thumbnail’ ); featured image dimensions customizable in Media Settings
• the_post_thumbnail( ‘medium’ ); featured image dimensions customizable in Media Settings
• the_post_thumbnail( ‘large’ ); featured image dimensions customizable in Media Settings
• the_post_thumbnail( ‘full’ ); the featured image will be displayed in the original dimensions (as uploaded)
• the_post_thumbnail( ‘custom’ ); any custom argument previously defined in functions.php
• the_post_thumbnail( array( 640, 480 ) ); any custom defined dimensions

Now we can add some CSS styles to the image to customize the it’s apparience completely. Let’s just center the image and add a tiny frame around it. Copy this code into your theme’s style sheet and and modify it according to your needs:

.featured-image img {
    display: block;
    margin: 0 auto;
    padding: 10px;
    background: antiquewhite;
    border: 1px solid grey;
}

More about how to display WordPress featured image

To learn more abut WordPress featured images and how to display them on your web site check out the following references:

• WordPress Theme Handbook
• WordPress Code Reference