Documentation Image Resizing And Cropping

Image Resizing And Cropping

Overview #

WordPress.com automatically handles images in ways that should help minimize the need to manually perform image resizing, cropping and optimization, e.g.

  • For high-DPI (aka Retina) devices, we automatically serve higher resolution versions of images in most cases; you should not need to upload or reference separate higher-resolution images. (This does not take effect for graphics defined by CSS, canvas, SVG, etc.)
  • In theme images, we perform automatic lossless compression on PNG and JPEG images that can be losslessly compressed, and automatically commit the compressed version to your theme’s subversion repository.

We have a few different solutions available if you need to create thumbnail versions of your images. Which method you should use depends on where the image is hosted and where the image will be displayed.

↑ Top ↑

For Posts And Pages #

This is the most common situation, where you want to have an image that is representative of the post or page.

To do this, you’ll want to use WordPress’s built-in Featured Image functionality. Setting the image is really easy. After having done so, you can access and display this image from within your theme. You can even use a different sized thumbnail depending on where you are (single post view, multi-post view, etc.).

You can also define additional image sizes by using the add_image_size function:

add_action( 'after_setup_theme', 'x_setup_image_sizes' );

function x_setup_image_sizes() {
    add_image_size( 'article-image', 300, 300 );
    add_image_size( 'article-image-cropped', 300, 300, true ); // this will force the image size to 300x300 by cropping it
}

Unlike a self-hosted WordPress install, WordPress.com will generate these images on-the-fly.

↑ Top ↑

Multiple Post Thumbnails #

If you’ve ever wanted more than one Featured Image on a post, check out the Multiple Post Thumbnails plugin.

↑ Top ↑

Custom Cropping / Editing Thumbnails #

If your editorial team needs complete control over the crops for images, you can use the WP.com Thumbnail Editor plugin

↑ Top ↑

For Other Uploaded Images #

If the image file is hosted on our websevers, i.e. yourblog.files.wordpress.com, then you can do some on-the-fly resizing and cropping using some query string parameters.

Set a w value to control the width, a h if you want to control the height, and/or crop=1 if you want to crop to those exact width and heights. We have a helper function that can handle this for you.

Example:

wpcom_vip_get_resized_attachment_url( $attachment_id, 100, 50, true );

That will get you the following URL:

http://vip.files.wordpress.com/2010/09/wpcomlogo.png?w=100&h=50&crop=1

↑ Top ↑

For Other Locations #

We also have functionality for resizing and cropping images that are hosted anywhere (both on our servers and elsewhere). Here’s some example code:

echo '<img src="' . wpcom_vip_get_resized_remote_image_url( $url, $width, $height ) . '" alt="Image" />';

This function will return the URL to a resized and then cropped version of $url, served off of our CDN and escaped of all HTML entities. If you want the raw URL (with no HTML escaping), pass false as a fourth parameter.

This is powered by our own Photon service which we use to “edit” images. It’s important to not call this RESTful API directly, but to use the function described above. If you are looking to edit the image in another way, give us a holler.

Note that this function will only work on WordPress.com or on a self-hosted test site which is public, and not your local test environment, since the images need to be publicly accessible.