1. Code
  2. Theme Development

Using Custom Image Sizes in Your Theme and Resizing Existing Images to the New Sizes


In this tutorial you will learn how to generate custom sized images for you to use in your WordPress theme. Why use custom image sizes? So you won't have to edit every image you upload to the Media Library. This way every image uploaded will get all the custom defined image sizes generated automatically. It can be inserted into the post or page using the Media Gallery or from the loop. Continue reading to find out how.

Step 1 Defining Custom Image Sizes

For your theme to support custom image sizes you have to edit the functions.php file found in your themes folder. Open your theme's functions.php and check if you have a line that looks like this:

This hook is called during a theme's initialization. It is generally used to perform basic setup, registration, and initialization actions for a theme, where "function_name" is the name of the function to be called.

If you found a line like that, then also find the method with the same name as the 2nd parameter from that add_action method.

If you can't find a line that looks like that you should add it, and also create a method names as the 2nd parameter:

Now to enable post thumbnails for your theme add the following lines in the method defined above:

Step 2 Displaying Images With Custom Sizes

Insert Custom Sized Image Into Post Using Media Gallery

To insert an image inside a post or page from the media gallery insert the following filter into the functions.php file:

What this code does, is it merges your custom image sizes with the one defined within WordPress so the result will be the image below.

Media Gallery custom sized image choose

Insert Custom Sized Image Inside the Loop

To display for example the image that was named "featured-image", inside the loop you have to add these lines:

This will check if the post/page has any image attached and will output an <img> tag showing the image at the desired size.

Step 3 Resizing Existing Images

For this task there is a plugin to help out, Regenerate Thumbnails. It can regenerate all, a batch, or individual images. If changing image sizes and regenerating them, the images with the previous dimensions will not be deleted.


Let's say you would like to make use of this feature within your theme. From the /wp-content/themes/name-of-the-theme folder open functions.php with your favorite text editor. If your theme doesn't have an after_setup_theme action defined, you must add one. The code for the custom image sizes will be added into that defined method.

Note: these are reserved image size names: thumb, thumbnail, medium, large, post-thumbnail. Adding a custom image size with a reserved name will override its predefined values.

Editing the content.php or content-single.php or content-page.php files, you can show the image with the appropriate size for the post header putting it below or under the post title.

To make the other two custom sizes choosable from the Media Gallery add the following filter:

A real life example of how this works and how it can be used:



How to generate a gallery with custom image sizes and add some JavaScript to zoom the images and switch between them (mouse and keyboard).

Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.