Responsive images are automatically supported by WordPress core. Image markup will automatically include
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.
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
Example output of
sizes attributes generated by default for an image file:
<img width="300" height="300" src="https://mytestsite.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://mytestsite.go-vip.net/wp-content/uploads/2023/04/IMG_1234.jpg 3024w, https://mytestsite.go-vip.net/wp-content/uploads/2023/04/IMG_1234.jpg?resize=150,150 150w, https://mytestsite.go-vip.net/wp-content/uploads/2023/04/IMG_1234.jpg?resize=300,300 300w, https://mytestsite.go-vip.net/wp-content/uploads/2023/04/IMG_1234.jpg?resize=768,768 768w, https://mytestsite.go-vip.net/wp-content/uploads/2023/04/IMG_1234.jpg?resize=1024,1024 1024w, https://mytestsite.go-vip.net/wp-content/uploads/2023/04/IMG_1234.jpg?resize=1536,1536 1536w, https://mytestsite.go-vip.net/wp-content/uploads/2023/04/IMG_1234.jpg?resize=2048,2048 2048w, https://mytestsite.go-vip.net/wp-content/uploads/2023/04/IMG_1234.jpg?resize=1568,1568 1568w" sizes="(max-width: 300px) 100vw, 300px">
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
srcsetfor all registered image sizes, regardless of the image’s aspect ratio.
- When images are output by functions such as
the_post_thumbnail(), the generated
srcsetwill only include other registered image sizes that share the same aspect ratio. For example, the default size for
thumbnailhas a 1:1 aspect ratio because it is set to 150 wide by 150 high with a hard crop. The
srcsetfor an image output at
thumbnailsize 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
srcsetfor that image. For example, if an image is uploaded with the original dimensions 380×300, the
srcsetfor that image will not include
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' );
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
$ vip @mytestsite.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
There are a few possible resolutions to intermediate file URLs that return a
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
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:
Will be filtered as:
This method can be tested by adding the
jetpack-photon=yes query parameter to a URL. For example:
define( 'WPCOM_VIP_USE_JETPACK_PHOTON', true );
Last updated: December 26, 2023