The add_image_size() WordPress PHP function registers a new image size. This allows you to specify custom dimensions and cropping behavior for images.
Usage
Below is a standard way of using this function. Let’s say you want to create an image size called ‘category-thumb’ with a width of 300 pixels.
add_action( 'after_setup_theme', 'my_theme_setup' );
function my_theme_setup() {
add_image_size( 'category-thumb', 300 ); // 300 pixels wide and unlimited height
}
Parameters
- $name (string, required): Image size identifier.
- $width (int, optional): Image width in pixels. Default 0.
- $height (int, optional): Image height in pixels. Default 0.
- $crop (bool|array, optional): Image cropping behavior. If false, the image will be scaled (default). If true, image will be cropped to the specified dimensions using center positions. If an array, the image will be cropped using the array to specify the crop location. Array values must be in the format: array( x_crop_position, y_crop_position ) where: x_crop_position accepts: ‘left’, ‘center’, or ‘right’. y_crop_position accepts: ‘top’, ‘center’, or ‘bottom’. Default: false.
More information
See WordPress Developer Resources: add_image_size()
This function was implemented in WordPress 2.9.0. It’s usually used in a theme’s functions.php file and always with the “after_setup_theme” action hook. Related functions include remove_image_size(), has_post_thumbnail(), the_post_thumbnail(), get_post_thumbnail_id(), get_the_post_thumbnail(), and set_post_thumbnail_size().
Examples
Set Up A Square Thumbnail
In this example, we’re setting up a ‘square-thumb’ size that’s 200×200 pixels and cropped to the center.
add_action( 'after_setup_theme', 'my_theme_setup' );
function my_theme_setup() {
add_image_size( 'square-thumb', 200, 200, true ); // Cropped to 200x200 pixels
}
Set Up A Wide Thumbnail
Here we are defining a wide thumbnail of 400×200 pixels. This size could be perfect for a slider or carousel.
add_action( 'after_setup_theme', 'my_theme_setup' );
function my_theme_setup() {
add_image_size( 'wide-thumb', 400, 200, true ); // Cropped to 400x200 pixels
}
Set Up An Uncropped Thumbnail
In this case, we define an uncropped thumbnail size. The image will be scaled to fit within the defined dimensions while maintaining the aspect ratio.
add_action( 'after_setup_theme', 'my_theme_setup' );
function my_theme_setup() {
add_image_size( 'large-thumb', 500, 500, false ); // Scaled to fit within 500x500 pixels
}
Set Up Custom Crop Position
This example shows how to define a custom crop position. The image will be cropped to 300×300 pixels with the cropping position towards the ‘left’ and ‘top’.
add_action( 'after_setup_theme', 'my_theme_setup' );
function my_theme_setup() {
add_image_size( 'custom-thumb', 300, 300, array( 'left', 'top' ) ); // Cropped to 300x300 pixels, left top
}
Change Default Medium Size
This example changes the default medium size to 500×500 pixels. The size is set using the ‘update_option’ function.
add_action( 'after_setup_theme', 'my_theme_setup' );
function my_theme_setup() {
update_option( 'medium_size_w', 500 ); // Set the medium size width to 500 pixels
update_option( 'medium_size_h', 500 ); // Set the medium size height to 500 pixels
}
Remember, after adding new sizes, WordPress needs to regenerate the images. You can use plugins or WP-CLI commands to accomplish this.