Advanced media optimization

Creates additional product media URLs available directly through Liquid, enabling just-in-time image optimization and advanced transformations like preview images, background removal, smart cropping, and color adjustments. All delivered with ultra-low network latency for optimal performance.

This metafield automatically maps selected properties from the original product media array - filtered for Shopify hosted images only - and transforms the Shopify URLs to be proxied through our own optimization engine - powered by TwicPics - offering additional and more fine-grained transformation options compared to Shopify. The transformations are applied on-the-fly using URL parameters, so you can use them anywhere, not just in Liquid templates.

Once a URL with its applied transformations has been requested once, it will be cached for future use and served directly from our CDN with Cloudflare.

About transformations

Examples are taken from the TwicPics API reference, which is the complete reference of media transformations supported by the TwicPics API.

Fundamentally, a transformation is a single operation that can be applied to an image, like resize, crop, rotate, flip, blur, sharpen, tint etc. resize=200x200 is a simple example of a transformation.

Multiple transformations can be chained together using the character /. When adding a transformation to the chain, the parameters given are interpreted as if previous transformations had already been performed (ie. as if the source image was the result of the previous transformations).

For instance:

• resize=340/resize=50p will result in an image that is 170 pixels wide (50% of the resized image)
• resize=50p/focus=20x10 will put the focus point at coordinates 40x20 of the original source image

Bear in mind that you have fine-grained control over the quality of the image. You can use the quality parameter to control the compression level of the image, which is useful for reducing the file size. The default quality value is 70 (out of a scale from 1 to 100, 100 being the best), which is a good balance between quality and file size. You can experiment with different values to find the optimal compression level for your use case.

Details

When you initially enable this metafield, the individual product metafields will be set in a background task. If you have a large catalog, this may take anywhere from a few minutes to a few hours. Once the metafields are set, they will be updated in real-time

[
    {
        "id": "gid://shopify/MediaImage/47953429430610",
        "mediaContentType": "IMAGE",
        "height": 800,
        "width": 1200,
        "url": "https://cdn.espresso.pics/s/files/1/0920/1090/5938/files/650_orange_web.jpg?v=1731311038",
        "alt": "Orange"
    },
    {
        "id": "gid://shopify/MediaImage/47953429463378",
        "mediaContentType": "IMAGE",
        "height": 800,
        "width": 1200,
        "url": "https://cdn.espresso.pics/s/files/1/0920/1090/5938/files/650_black_web.jpg?v=1731311038",
        "alt": "Black"
    },
    ...
]

Example implementation

{% assign media_entries = product.metafields.espresso.media.value %}

{% for media in media_entries %}
    <img src="{{ media.url | append: '&resize=400/quality=90' }}" alt="{{ media.alt }}" />
{% endfor %}

Responsive images

The srcset feature of HTML allows browsers to automatically choose an image that is best suited for user’s screen resolution.

srcset requires providing multiple resized versions of every image. With url-based image transformations this is an easy task to accomplish.

There are two different scenarios where it is useful to use srcset:

• Images with a fixed size in terms of CSS pixels, but adapting to high-DPI screens (also known as Retina displays). These images take the same amount of space on the page regardless of screen size, but are sharper on high-resolution displays. This is appropriate for icons, thumbnails, and most images on pages with fixed-width layouts.
• Responsive images that stretch to fill a certain percentage of the screen (usually full width). This is best for hero images and pages with fluid layouts, including pages using media queries to adapt to various screen sizes.

srcset for high-DPI displays

For high-DPI display you need two versions of every image. One for 1x density, suitable for typical desktop displays (such as HD/1080p monitors or low-end laptops), and one for 2x high-density displays used by almost all mobile phones, high-end laptops, and 4K desktop displays. Some mobile phones have very high-DPI displays and could use even a 3x resolution. However, while the jump from 1x to 2x is a clear improvement, there are diminishing returns from increasing the resolution further. The difference between 2x and 3x is visually insignificant, but 3x files are two times larger than 2x files.

Assuming you have a media image metafield product.metafields.espresso.media (being an array of media entries) and you want to display it at a size of 960px, the code is as follows:

{% assign media_entries = product.metafields.espresso.media.value %}

{% for media in media_entries %}
    <img
      src="{{ media.url | append: '&resize=960' }}"
      srcset="{{ media.url | append: '&resize=1920' }} 2x"
    />∏

{% endfor %}

The srcset attribute adds another, high-DPI image. The browser will automatically select between the images in the src and srcset. In this case, specifying contain=1920 (two times 960 pixels) and adding 2x at the end, informs the browser that this is a double-density image. It will be displayed at the same size as a 960 pixel image, but with double the number of pixels which will make it look twice as sharp on high-DPI displays.

Note that it does not make sense to scale images up for use in srcset. That would only increase file sizes without improving visual quality. The source images you should use with srcset must be high resolution, so that they are only scaled down for 1x displays, and displayed as-is or also scaled down for 2x displays.

srcset for responsive images

When you want to display an image that takes a certain percentage of the window or screen width, the image should have dimensions that are appropriate for a visitor’s screen size. Screen sizes vary a lot, typically from 320 pixels to 3840 pixels, so there is not a single image size that fits all cases. With <img srcset> you can offer the browser several possible sizes and let it choose the most appropriate size automatically.

{% assign media_entries = product.metafields.espresso.media.value %}

{% for media in media_entries %}
    <img
      width="100%"
      src="{{ media.url | append: '&resize=960' }}"
      srcset="{{ media.url | append: '&resize=320' }} 320w,
              {{ media.url | append: '&resize=640' }} 640w,
              {{ media.url | append: '&resize=960' }} 960w,
              {{ media.url | append: '&resize=1280' }} 1280w,
              {{ media.url | append: '&resize=2560' }} 2560w"
    />

{% endfor %}

By default, the browser assumes the image will be stretched to the full width of the screen, and will pick a size that is closest to a visitor’s screen size. In the src attribute the browser will pick any size that is a good fallback for older browsers that do not understand srcset.

In the previous case, the number followed by x described screen density. In this case the number followed by w describes the image size. There is no need to specify screen density here (2x, etc.), because the browser automatically takes it into account and picks a higher-resolution image when necessary.

If the image is not displayed at full width of the screen (or browser window), you have two options:

• If the image is displayed at full width of a fixed-width column, use the first technique that uses one specific image size.
• If it takes a specific percentage of the screen, or stretches to full width only sometimes (using CSS media queries), then add the sizesattribute as described below.

sizes attribute

You can use the sizes attribute to specify the image size for different screen sizes:

{% assign media_entries = product.metafields.espresso.media.value %}

{% for media in media_entries %}
    <img
      style="max-width: 640px"
      sizes="(max-width: 640px) 100vw, 640px"
      srcset="{{ media.url | append: '&resize=320' }} 320w,
              {{ media.url | append: '&resize=480' }} 480w,
              {{ media.url | append: '&resize=640' }} 640w,
              {{ media.url | append: '&resize=1280' }} 1280w,
    />

{% endfor %}

In this example, sizes says that for screens smaller than 640 pixels the image is displayed at full viewport width; on all larger screens the image stays at 640px. Note that one of the options in srcset is 1280 pixels, because an image displayed at 640 CSS pixels may need twice as many image pixels on a high-dpi (2x) display.

See also