Customizing Post Thumbnails with post_thumbnail_html Filter Hook in WordPress

Post Thumbnails in WordPress are an important element when it comes to synbolizing an article with an image. Post thumbnails act as the face of an article. Sometimes, these post thumbnails need to be customized in order to fit our requirements. In today’s article, I am going to show you how we can customize our post thumbnail using the post_thumbnail_html filter hook with the help of a simple example.

Note that this article assumes you have experience with WordPress and familiar with template structure and basic functions. Let’s get started.

First let’s discuss a bit about what is a post_thumbnail and how do we include it in our posts.

What is a Post Thumbnail?

Like I mentioned earlier, a post thumbnail can be considered as a face of an article. While a post can have multiple images in its content, a post is always going to have one post thumbnail, alson known as a featured image. You can set it from the Edit Screen of the post. If you are using the Block Editor, it is at the top of the sidebar –

In case you are using the Classic Editor, you can set your Post Thumbnail / Featured Image from a metabox located at the bottom right of the Edit screen of the post –

If you are not able to see these sections, it probably means that post thumbnails are not enabled in your theme. In order to add support for post thumbnails in your theme, add the following code in your functions.php –

After saving the file, you should be able to see the section to set featured image.

How to add a post thumbnail in our theme

So far,we saw what is a post thumbnail and how can we set it in a post. But how to add it in our theme files. WordPress a couple of functions to do just that. If you have to check whether a post has a featured image set, you can check it using the has_post_thumbnail() function. If you want to print the featured image on the screen, you can do it with the the_post_thumbnail(). There are a few other functions which can take a look at in the WordPress codex functions reference.

So, if  we want to add a post thumbnail to a post, we do it in the single.php theme file. In case we want to add it in a page, we usually do it in page.php. It can be different depending on your theme structure. Refer to WordPress’ template hierarchy to find out which file you want to add the post thumbnail to. For article’s sake, I’m going to keep things simple and add a post thumbnail in a single post. So, the file we’re going to edit is single.php.

Go ahead and add the following code to single.php –

Again, this is very generic and we can customize the output by modifying the the_post_thumbnail() functions passing arguments based on our requirements.

Now, we have a post thumbnail being out put on our post. But now, we need to customize it in some way. This is where the post_thumbnail_html filter hook comes in.

Customizing the Post Thumbnail using post_thumbnail_html

Basically, post_thumbnail_html  is used to filter the HTML generated for the featured image of a post. We are going to see how this filter hook works using an example.

Let’s say we want to add <figure> tag around our post thumbnail. Let’s see how we can do it using the post_thumbnail_html  filter hook. Add the following code to your functions.php file –

A pretty straight forward example. In the above code, we hook the my_theme_add_figure_to_thumbnail callback function to the post_thumbnail_html filter hook. Our callback function is accepting $html as an argument (although, the callback function can accept more arguments, more on that later).

We reassign $html to include <figure>  tags around our HTML. You’ll notice that <figure>  tags get added around all our post thumbnails at the front-end.

This was the basic functinality of post_thumbnail_html in a nutshell. Now, let’s take a look at the arguments accepted by this hook.

post_thumbnail_html accepted arguments

As per the hook’s documentation, the callback function can accept 5 arguments –

$html

The HTML of the post thumbnail. It is the <img> tag for the post thumbnail with all attributes added to the tag. We used this argument in our earlier example.

$post_id

ID of the post to which the thumbnail belongs. It is helpful in case we want to target post thumbnails of a specific post.

$post_thumbnail_id

ID of the thumbnail. It is the attachment ID of the image used as the thumbnail. In case a post doesn’t have a thumbnail, this argument defaults to 0.

$size

The size of the thumbnail. In case a value is mentioned in the_post_thumbnail() as one of it’s arguments, $size gets the same value. Otherwise, it is post-thumbnail as the default value in WordPress.

$attr

String or array of attributes added to <img>  tag of the thumbnail.

Conclusion

So, this is it! We took a look at how we can customize our post thumbnail (featured image) using the post_thumbnail_html  filter hook using a simple example. There is a lot more we can do using this hook. We also went through the arguments accepted by the callback function which we can use to target specific posts, thumbnail sizes or attributes.

Hope you were able to learn something new in this article. If you would like to know more tips and tricks of WordPress, do check out our blog where we share similar content on a regular basis. See you in the next article!