Image Crop Sizes

In working with your media library, this article will help you to understand what image crop sizes your theme registers, how WordPress cropping works, and how to customize the crop sizes.

Default Crop Sizes

Below are default crop sizes for the framework, and what you’ll find in Jump Start. While it’s possible there might be slight variations, the sizes below are fairly consistent through all other framework 2.5+ themes, as well.

About WordPress Cropping

Before we get to how the framework registers image sizes and how to customize them, I think the following tidbits are important for you to understand about how WordPress handles crop sizes, in general.

Crop Sizes Need to Be Registered

Whether you’re working from a theme or plugin, to have a crop size, it needs to be registered with WordPress using the add_image_size() function to designate its unique name, dimensions and crop mode.

Cropped Images Are Generated at the Time of Upload

At the time you upload a new image, WordPress will cycle through all currently registered crop sizes and produce a cropped image version for each size.

So, this means that if you change your crop sizes, or switch themes or plugins that have different sizes, those sizes will not exist for your previously uploaded images. Luckily, for these scenarios, you can run the regenerate thumbnails plugin, and regenerate all cropped images for everything you have already uploaded in your Media Library.

Cropped Images Are Generated Only If the Original Image Is Large Enough

When WordPress is cycling through creating all of the crop sizes for an image, it will skip over any sizes that are larger than the original image you’re uploading.

So, if you upload an image and isn’t big enough to meet a crop size, it won’t get made. Then, on your site when that image size is retrieved, it will simply return the original image you uploaded, as a fallback.

Hard Crop vs Soft Crop

When you register an image size, you can designate whether its crop mode is hard or soft.

(1) A hard crop is most common; this means that the image will always be cropped to the exact dimensions specified, which generally results in some of the original image being cut off. (2) Alternatively, a soft crop will never cut off any of the image; WordPress will scale the image down until it fits within the dimensions specified, maintaining its original aspect ratio.

How the Framework Registers Crop Sizes

The framework creates a filterable array of crop sizes, loops through them, and registers each one with add_image_size(). So we’ve got an array of crop sizes formatted something like the following.

apply_filters('themeblvd_image_sizes', array(
    'example' => array(
        'name' 		=> 'Example Size #1',
        'width' 	=> 400,
        'height'	=> 200,
        'crop' 		=> true
    ),
    'example_2' => array(
        'name'		=> 'Example Size #2',
        'width'		=> 600,
        'height'	=> 250,
        'crop'		=> true
    )
    // etc ...
))

And then the framework loops through the filterable array of sizes resulting in something like the following.

add_image_size( 'example', 400, 200, true );
add_image_size( 'example_2', 600, 250, true );

If you’d like to see where this actually happens within your theme, see the themeblvd_get_image_sizes() function in /framework/helpers/media.php.

Customizing Framework Crop Sizes

As mentioned previously, the array of crop sizes is filterable, before the sizes are actually registered with WordPress. Using this themeblvd_image_sizes filter, is how you can customize these sizes, from your child theme’s functions file.

Change a Crop Size’s Dimensions

For the following example, we can find a couple of crop ID’s from the table above, and change their dimensions.

function my_image_sizes( $sizes ) {
	
	$sizes['slider-x-large']['width'] = 1400;
	$sizes['slider-x-large']['height'] = 500;

	$sizes['slider-large']['width'] = 1200;
	$sizes['slider-large']['height'] = 400;

	return $sizes;
}
add_filter('themeblvd_image_sizes', 'my_image_sizes');

Use A Soft Crop Mode

For this, you just want to change your crop size’s crop key to false. A good example is with the tb_grid crop size that get used with post grids. Maybe you don’t like that your images get cut off and you want all images to retain their aspect ratios.

function my_image_sizes( $sizes ) {
	$sizes['tb_grid']['crop'] = false;
	return $sizes;
}
add_filter('themeblvd_image_sizes', 'my_image_sizes');

Remove Crop Sizes

Maybe there are some crop sizes associated with features of the framework you’re simply not using and you’d prefer not to have these extra images generated on your server every time you upload a new image to your media library. So, you’d simply unset() those items by their name keys from the framework’s array of sizes.

function my_image_sizes( $sizes ) {
	
	unset( $sizes['tb_square_x_large'] );
	unset( $sizes['tb_square_large'] );
	unset( $sizes['tb_square_medium'] );

	return $sizes;
}
add_filter('themeblvd_image_sizes', 'my_image_sizes');

Add Crop Sizes

If you want to register your own crop size, you could simply call add_image_size(). However, as an alternative approach, you could filter into the framework’s array of crop sizes to be registered, too.

This will allow your added crop size(s) to be present in case other plugins are doing anything with the framework’s filter. Additionally, it will also add it to the list of image sizes that get displayed when the user is inserting images into pages and posts.

function my_image_sizes( $sizes ) {
	
	$sizes['my_size'] = array(
		'name' 		=> 'My Size',
		'width' 	=> 500,
		'height' 	=> 300,
		'crop' 		=> true
	);

	return $sizes;
}
add_filter('themeblvd_image_sizes', 'my_image_sizes');