Web-Optimized Image Delivery

Learn how the Core Components can leverage AEM as a Cloud Service’s web-optimized image delivery features to deliver images more efficiently.


The web-optimized image delivery feature of AEM as a Cloud service delivers image assets from the DAM in WebP format. WebP can reduce the download size of an image by about 25% on average, which results in faster page loading.

Activating web-optimized image delivery in Core Components is simple, and because all common browsers support WebP, the experience is transparent to the end user. The only difference they will notice is that content loads faster!

Activating Web-Optimized Image Delivery for Core Components

To enable web-optimized image delivery, edit a page template and simply activate the option Enable Web Optimized Images within the design dialog of the Image Component. This option is available for v1, v2, and v3 of the Image Component.

If you are not familiar with design dialogs and AEM’s page templates, please review this document.

Enabling web-optimized image delivery in the design dialog

That’s it! Images are now delivered by the Image Component in WebP format.

Once you activate web-optimized imaged delivery, you may want to also check your dispatcher configuration to verify that it does not block request to the image service. URLs of this service take the following form.


This can be generalized with this regular expression.


Verifying WebP Delivery

Web-optimized image delivery is transparent to the consumer of the content and does not affect the markup. The only thing that an end user will notice is faster load time.

Therefore to observe the actual change of behavior, you must view the page source.

  1. In AEM, edit a page that is based off of the template where you activated web-optimized image delivery for the Image Component.
  2. Within the page editor, select the Page Information button at the top-left and then View as Published.
  3. Using your browsers developer tools, view the source of the page and see how the rendered markup stays the same, but that the image in the src attribute points to the URL of the new image service.

When Web-Optimized Image Delivery is Unavailable

Web-optimized image delivery is only available in AEM as a Cloud Service. In cases where it is unavailable such as running AEM 6.5 on premise or on a local development instance, image delivery will fall back to using the Adaptive Image Servlet.

Just as enabling web-optimized image delivery does not affect the markup, falling back to the Adaptive Image Servlet likewise has no effect on the markup since only the URL in the src attribute of the img element is changed.

Frequently-Asked Questions

Why is there no option to enable web-optimized images in my environment?

The feature is only available on AEM as a Cloud Service. Running AEM locally or on premise, the Image Component falls back to using the Adaptive Image Servlet.

Why doesn’t the service work with the local SDK?

When using the AEM SDK on localhost, the image service isn’t available, and the image rendering falls back to using the Adaptive Image Servlet.

To use the web-optimized image delivery service, deploy the project to a AEMaaCS development environment to be able to test precisely how the image service behaves with the image service.

Why doesn’t the service work for some images on my page?

The image service only works for assets located under /content/dam and it won’t work for images uploaded directly to the page and stored under a cq:Page object. Such assets will still be delivered with the Adaptive Image Servlet as a fallback.

Why does the service display a worse quality image or limits the size of images?

The web-optimized image service considers all image renditions that are 2048px and smaller and picks the largest of those as the base on which it will apply the requested settings (width, crop, format, quality, etc).

The image service will never upscale images. These renditions therefore define the best size and quality that the image service will be able to deliver. Therefore make sure that your assets all have the 2048px zoom rendition, and if they don’t, reprocess them.

The URL of my images still end with .JPG or .PNG, not .WEBP, and there’s no SRCSET attribute or PICTURE element. Is this really using optimized web formats?

To deliver WebP formats, the web-optimized image delivery service uses a technique called “content negotiation”. This consists in returning a WebP file format, even when requesting a JPG or PNG file extension, but only when the browser making the request provided an image/webp HTTP accept header. Browsers supporting this technique can then provide this header, and older browsers will still get the JPG or PNG file format.

The advantage of this technique is that the img element and its attributes can remain the same, which will lead to an optimal compatibility for existing sites, and guarantee the smoothest possible path to transition towards web optimized image delivery.

Can I use web-optimized image delivery with my own component?

Yes, the web-optimized image delivery service can be used by custom components. Adobe recommends extending the Image Component in this case.

The following is a service interface that can be used to help generating the asset URL.

com.adobe.cq.wcm.spi.AssetDelivery.getDeliveryURL(Resource resource, Map<String, Object> parameterMap)

This service takes an asset resource as mandatory first parameter and can take an optional map of desired image transformations that are to be applied which can contain the following parameters.

  • path – Asset ID that is to be delivered, must be of pattern ([^:\[\]\|\*\/]+) (e.g.: unicorn–1234)
  • seoname – User-defined, SEO-centric name to be appended to the image URL, may contain hyphens, must be of pattern ([\w-]+) (e.g.: my-friend-the-unicorn)
  • format – The desired image format, can be gif, png, png8, jpg, pjpg, bjpg, webp, webpll, webply (e.g.: webp)
  • preferwebp – If possible, deliver WebP output, ignoring the format parameter (see FAQ about content negotiation), boolean (e.g.: true)
  • width – The desired image resolution in pixels, must be greater than 1 (e.g.: 400)
  • quality – The desired compression, between 1 and 100 (e.g.: 75)
  • c – The desired image cropping coordinates, comma-separated pixel values (e.g.: 100,100,400,200)
  • r – The desired image rotation, can be 90, 180, 270 (e.g.: 90)
  • flip – The desired image flipping, can be h, v, hv (e.g.: h)

What is the URL of an image delivered by the new image service?

See the previous section Activating Web-Optimized Image Delivery for Core Components for an example URL and regular expression.

Can images fail to display after enabling web optimized images?

No, this should never happen.

On this page