add_image_size()WP 2.9.0

Registers a new image size (thumbnail).

Registration means that WordPress while uploading an image, in addition to the basic sizes, will create one more file with specified sizes (width and height).

You can call this function at any time, but it is better to do it early, so that you can turn off the size later.

  • For plugin, it's better to do it on hook plugin_loaded with priority 0.
  • Fro theme, it's better to call it directly in the functions.php file body.

In order you can set post thumbnail in admin edit page, you need to activate this feature with add_theme_support( 'post-thumbnails' ). Place call of this function in funstions.php template file.

To create thumbnails on the fly with any size, instead of this feature, use my plugin Kama Thumbnail.

Use remove_image_size() to remove a previously created size.

Reserved size names

thumb, thumbnail, medium, large, post-thumbnail.

The names "thumb" and "thumbnail" are aliases (synonyms) and refer to the same files.

See also the description of the image_downsize() function.

You can also set the options for the created thumbnail like this:

update_option( 'thumbnail_size_w', 160 );
update_option( 'thumbnail_size_h', 160 );
update_option( 'thumbnail_crop', 1 );

When creating your own theme for the WP themes catalog, the name of the new size should contain the name of the theme, see more in this article. For example:

add_image_size( 'mytheme-mini', 200, 200, true );

No Hooks.

Return

null. Nothing (null).

Usage

add_image_size( $name, $width, $height, $crop );
$name(string) (required)
Image size name (identifier).
$width(int) (required)
Image width in pixels.
Default: 0
$height(int) (required)
Image height in pixels.
Default: 0
$crop(true/false/array)

Define how to create the thumbnail: whether to crop images to specified width and height or resize. An array can specify the positioning of the crop area.

  • false (default) - scaling: images will be scaled, not cropped. The thumbnail is created by one of the appropriate sides: the specified width or height. The final picture will not exactly match the specified dimensions.

  • true - cropping: images will be cropped to the specified dimensions using center positions.

  • array( x_position, y_position ) - specifies the crop position, i.e. if you specify the [ 'right', 'top' ] array, then the image will be cropped from the upper-right corner.
    • x_position - accepts left, center, right.
    • y_position - accepts top, center, bottom.

"crop" works only for newly created images. If the site already has images in it's library the new add image size will not be processed for this files.

Default: false

Examples

0

#1 Add new thumbnail sizes

Register a new thumbnail size by adding this code in the functions.php template file:

if ( function_exists( 'add_theme_support' ) ) {

	add_theme_support( 'post-thumbnails' );
	// default post thumbnail size
	set_post_thumbnail_size( 150, 150 );
}

if ( function_exists( 'add_image_size' ) ) {

	// 300 in width and no limit in height
	add_image_size( 'category-thumb', 300, 9999 );      

	// Crop an image
	add_image_size( 'homepage-thumb', 220, 180, true );
}
0

#2 $crop parameter

Scaling $crop = false

This line will tell WP that when you upload a new file, you need to make a smaller copy of it. In this case, the thumbnail will be adjusted to the width or height, depending on which side is more suitable, and the opposite side will be reduced proportionally and most likely will not be more than the specified size. For example, we have the original image 2500x1800 pixels and we make a thumbnail 220x180 pixels. The picture will be reduced to the size - 250x180 px, i.e. the height will be 180, as we indicated, but the width will be higher than the specified 250 but not 220 as we set. In this case, the image is not cropped and the reduced copy saves the proportions of original image.

add_image_size( 'homepage-thumb', 220, 180 );
Cropping $crop = true

If you set the fourth parameter to true, the thumbnail will be reduced and cut to exactly the specified size. For example, we have the original image 2500x1800 pixels we make a thumbnail 220x180 pixels. The original will be reduced to the height 180xp (then the resized image width as equal to 250px), and the width will be clipped at the edges by 15px and in the end, we get the reduced copy: 220х180 pixels:

add_image_size( 'homepage-thumb', 220, 180, true );
Hard crop with positions $crop = [ x, y ]

Since version 3.9, it is possible to specify the cropping position. Let's add the size of the thumbnail, which will be 220x220 pixels and will be a fragment from the original, which will be taken from the upper left corner (left, top):

add_image_size( 'custom-size', 220, 220, [ 'left', 'top' ] );

Х position can be: 'left' 'center' or 'right'.
Y position can be:: 'top', 'center' or 'bottom'.

0

#3 Resize by the specified side

To reduce the image on one of the sides we need, we can specify the opposite side of a huge value. For example, we have a picture of 2500х1800, and we need to get the thumbnail 500х1800:

add_image_size( 'homepage-thumb', 500, 9999 );
0

#4 How to use new sizes in code?

Let's say that, we have registered 3 non-standard sizes: post-thumbnail, category-thumb, homepage-thumb. Now to use these sizes (display images in the template), you can use the following functions:

Featured image (featured image)

To use the new size when displaying a picture which set as a "featured image" of the post, you need to use the_post_thumbnail() function in the template file, like so:

if( has_post_thumbnail() ){
	the_post_thumbnail( 'category-thumb' ); // category-thumb - size name
}
A new size in the selection of sizes when you insert images (admin panel)

To add a new size to the sizes selection when you insert a picture in the post, you need to use the image_size_names_choose filter, in which you need to add a size and specify a friendly name for it:

add_filter( 'image_size_names_choose', 'my_custom_sizes' );
function my_custom_sizes( $sizes ) {
	return array_merge( $sizes, array(
		'category-thumb' => 'My size',
	) );
}
For main media files (PHP/Templates)

You can also display images (by size) directly from the WordPress media library by image ID. To do this, use the wp_get_attachment_image() function:

// It is assumed that you have a picture with ID 42 in the media library...
echo wp_get_attachment_image( 42, 'category-thumb' );

If we need to get only the URL of the image and not the ready <img> tag, then use the function wp_get_attachment_image_src().

Plugins

  1. Regenerate Thumbnails - this plugin allows you to create new sizes for each existing image. Useful when you have changed (via Settings > media Files) or added new image sizes, but the media library already has images.

  2. Force Regenerate Thumbnails - deletes previously created images and creates new ones based on current sizes settings.

  3. AJAX thumbnail rebuild - allows you to rebuild the thumbnails. Useful if you have used the add_image_size() function when you already have images uploaded in the library. (This is a slow plugin, but there are no errors with a lack of allocated memory).

  4. Simple Image Sizes - allows you to create new thumbnail sizes directly from the Media panel. It also knows how to recreate thumbnails. It adds new sizes to the selection for posts so you can insert new sizes into posts. You can choose which of the sizes you would like to recreate and for which types of posts you need to do it.

Notes

  • Global. Array. $_wp_additional_image_sizes Associative array of additional image sizes.

Changelog

Since 2.9.0 Introduced.

add_image_size() code WP 6.4.3

function add_image_size( $name, $width = 0, $height = 0, $crop = false ) {
	global $_wp_additional_image_sizes;

	$_wp_additional_image_sizes[ $name ] = array(
		'width'  => absint( $width ),
		'height' => absint( $height ),
		'crop'   => $crop,
	);
}