Skip to content

Responsive images

Responsive images are automatically supported by WordPress Core. Image markup will automatically include srcset and sizes attributes for images uploaded to a WordPress site’s Media Library. These attributes enable web browsers to automatically use and display the most suitable image size based on a device’s screen size.

WordPress Core includes a default set of image sizes (i.e. full, large, medium_large, medium, thumbnail) and those sizes are included in the srcset value for an image. If additional custom image sizes are registered on a site by an active theme or plugin, those sizes will also be included in the srcset.

Example output of srcset and sizes attributes generated by default for an image file:

<img width="300" height="300" 
src="https://example-app.go-vip.net/wp-content/uploads/2023/04/IMG_1234.jpg?w=300" 
class="attachment-medium size-medium wp-post-image" alt="example image" decoding="async" loading="lazy" 
srcset="https://example-app.go-vip.net/wp-content/uploads/2023/04/IMG_1234.jpg 3024w, 
https://example-app.go-vip.net/wp-content/uploads/2023/04/IMG_1234.jpg?resize=150,150 150w, 
https://example-app.go-vip.net/wp-content/uploads/2023/04/IMG_1234.jpg?resize=300,300 300w, 
https://example-app.go-vip.net/wp-content/uploads/2023/04/IMG_1234.jpg?resize=768,768 768w, 
https://example-app.go-vip.net/wp-content/uploads/2023/04/IMG_1234.jpg?resize=1024,1024 1024w, 
https://example-app.go-vip.net/wp-content/uploads/2023/04/IMG_1234.jpg?resize=1536,1536 1536w, 
https://example-app.go-vip.net/wp-content/uploads/2023/04/IMG_1234.jpg?resize=2048,2048 2048w, 
https://example-app.go-vip.net/wp-content/uploads/2023/04/IMG_1234.jpg?resize=1568,1568 1568w" 
sizes="(max-width: 300px) 100vw, 300px">

Default behavior

On a typical WordPress install, a separate (intermediate) image file is generated for each registered image size when an image is uploaded. The dimensions of each of those intermediate file sizes, and the paths to each generated image, are stored in the attachment post for the image file in the database.

However, on the VIP Platform separate intermediate images are not generated for image files. The registered image sizes for a file are dynamically generated on demand. Only the original uploaded file is stored on the VIP File System, and only the dimensions of the original uploaded file—and the path to its location—are stored in the image’s attachment post metadata.

By default, all registered image sizes (default and custom) will be included in the generated srcset for an image.

  • Images added to post content with the Image Block will generate srcset for all registered image sizes, regardless of the image’s aspect ratio.
  • When images are output by functions such as the_post_thumbnail(), the generated srcset will only include other registered image sizes that share the same aspect ratio. For example, the default size for thumbnail has a 1:1 aspect ratio because it is set to 150 wide by 150 high with a hard crop. The srcset for an image output at thumbnail size will only include other image sizes if:
    • Another registered image size is also set to hard crop at a 1:1 pixel ratio (e.g. 200×200).
    • The originally uploaded image size is already a 1:1 aspect ratio.
  • Only the registered image sizes that have a smaller pixel dimension than the originally uploaded image (full) size will be included in the srcset for that image. For example, if an image is uploaded with the original dimensions 380×300, the srcset for that image will not include large (1024), or medium_large (768).

Disable VIP’s responsive image support

Customers can optionally implement their own custom srcset solutions for their WordPress applications. For a custom solution to work as expected, VIP’s responsive image support must be disabled by setting the vip_go_srcset_enabled filter to __return_false. It is recommended to add the filter to a custom single file plugin located in /client-mu-plugins. For WordPress multisite environments, logic can be added to the custom plugin that selectively disables the filter per-network site if needed.

add_filter( 'vip_go_srcset_enabled', '__return_false' );

Troubleshooting

WordPress sites that have migrated to the VIP Platform might have attachment posts with metadata that points to separate intermediate files (e.g. image-300x300.jpg). Metadata for an attachment can be reviewed by running the WP-CLI command wp post meta get _wp_attachment_metadata against an image file’s attachment ID.

This example command demonstrates the WP-CLI command being run with VIP-CLI to retrieve metadata for an image file with the attachment ID 1234:

$ vip @example-app.develop --y -- wp post meta get 1234 _wp_attachment_metadata

URLs for separate intermediate image sizes will render correctly in srcset as long as:

  • That specific intermediate image file is stored in the VIP File System.
  • The file path in the attachment metadata is a valid path that points to the correct location of the file on the VIP File System.

If the intermediate file specified in the metadata was not imported to the VIP File System, or the path is invalid for other reasons, URLs for that image size will return a 404 in the generated srcset.

There are a few possible resolutions to intermediate file URLs that return a 404 in srcset.

Import the intermediate images

If intermediate images were not included in the initial media import, and the files are still available, re-import all of the site’s media files. By default, the VIP-CLI vip import media command excludes files identified as intermediate images. To override that default, include the  -i option when running the import media command.

Reset the attachment metadata

Attachment metadata can be modified by executing a custom CLI command with VIP-CLI. This method requires writing a custom CLI command that can iterate through a site’s attachment posts and delete size arrays, if they exist, in the attachment’s metadata. This code example demonstrates a method for deleting existing size arrays in the attachment’s metadata:

$meta = wp_get_attachment_metadata( $id );
$meta['sizes'] = [];
wp_update_attachment_metadata( $id , $meta );

Enable Jetpack Photon dynamic file resizing

The WPCOM_VIP_USE_JETPACK_PHOTON constant can be set as true to take advantage of Jetpack Photon dynamic image resizing. If enabled on a VIP site, filters that are defined within VIP MU plugins will strip dimensions from file names (e.g. -150x150) and append the dimensions as resize query parameters to the file path.

For example, this intermediate file path: https://example.com/wp-content/uploads/2023/01/example-image-600x400.jpg
Will be filtered as: https://example.com/wp-content/uploads/2023/01/example-image.jpg?resize=600%2C400

This method can be tested by adding the jetpack-photon=yes query parameter to a URL. For example:
https://example.com/example-post/?jetpack-photon=yes

vip-config/vip-config.php
define( 'WPCOM_VIP_USE_JETPACK_PHOTON', true );

Last updated: December 26, 2023

Relevant to

  • WordPress