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

Plugin API/Filter Reference/image resize dimensions


Since version 3.4, the image_resize_dimensions filter is used to filter the thumbnail and alternative sizes dimensions of image assets during resizing operations. This enables the override of WordPress default behavior on image resizing, including the thumbnail cropping.

A plugin (or theme) can register as an image resizing filter with the code:

<?php add_filter( 'image_resize_dimensions', 'filter_function_name', 10, 5 ) ?>

Where 'filter_function_name' is the function WordPress should call when the image resizing is being executed. Note that the filter function must return an array matching the parameters to imagecopyresampled(), or false if the resizing is impossible, or should not occur, or null to fallback to WordPress default behavior.

filter_function_name should be unique function name. It cannot match any other function name already declared.


(null) (required) Variable to be filtered.
Default: None
(integer) (required) Original image width in pixels.
Default: None
(integer) (required) Original image height in pixels.
Default: None
(integer) (required) Destination image width in pixels.
Default: None
(integer) (required) Destination image height in pixels.
Default: None
(boolean) (required) Flag to enable image croping.
Default: None


This example filters the image resizing dimensions to force WordPress to crop thumbnails by keeping the top of the image, instead of the default center.

add_filter( 'image_resize_dimensions', 'custom_image_resize_dimensions', 10, 6 );
function custom_image_resize_dimensions( $payload, $orig_w, $orig_h, $dest_w, $dest_h, $crop ){

	// Change this to a conditional that decides whether you 
	// want to override the defaults for this image or not.
	if( false )
		return $payload;

	if ( $crop ) {
		// crop the largest possible portion of the original image that we can size to $dest_w x $dest_h
		$aspect_ratio = $orig_w / $orig_h;
		$new_w = min($dest_w, $orig_w);
		$new_h = min($dest_h, $orig_h);

		if ( !$new_w ) {
			$new_w = intval($new_h * $aspect_ratio);

		if ( !$new_h ) {
			$new_h = intval($new_w / $aspect_ratio);

		$size_ratio = max($new_w / $orig_w, $new_h / $orig_h);

		$crop_w = round($new_w / $size_ratio);
		$crop_h = round($new_h / $size_ratio);

		$s_x = floor( ($orig_w - $crop_w) / 2 );
		$s_y = 0; // [[ formerly ]] ==> floor( ($orig_h - $crop_h) / 2 );
	} else {
		// don't crop, just resize using $dest_w x $dest_h as a maximum bounding box
		$crop_w = $orig_w;
		$crop_h = $orig_h;

		$s_x = 0;
		$s_y = 0;

		list( $new_w, $new_h ) = wp_constrain_dimensions( $orig_w, $orig_h, $dest_w, $dest_h );

	// if the resulting image would be the same size or larger we don't want to resize it
	if ( $new_w >= $orig_w && $new_h >= $orig_h )
		return false;

	// the return array matches the parameters to imagecopyresampled()
	// int dst_x, int dst_y, int src_x, int src_y, int dst_w, int dst_h, int src_w, int src_h
	return array( 0, 0, (int) $s_x, (int) $s_y, (int) $new_w, (int) $new_h, (int) $crop_w, (int) $crop_h );



As of WordPress 3.6 this hook is applied in the following locations:

This hook may also frequently be applied by plugins.

See Also