Shopify Images: Fixing Image Optimisation in Shopify

What Shopify does for you, and what it leaves to the theme

Images you upload to products, collections, the Files area or theme image settings are stored by Shopify and served from its CDN at cdn.shopify.com, or through your own domain on newer setups. The CDN produces resized copies on request, so one upload can be served at many widths, and it chooses a modern format such as WebP for browsers that accept it. You do not need an extra CDN or format plugin for that part.

What the CDN cannot decide is how the theme asks for images. That is controlled by Liquid in your theme and by what you enter in the admin:

• Which width is requested, and whether a srcset offers smaller ones for phones.
• Whether the sizes attribute tells the browser how wide the image really is on screen.
• Whether width and height are printed, so space is reserved.
• Whether the first large image is loaded early or lazy-loaded.
• Whether alt text exists and is printed.
• Whether an image comes through the resizing pipeline at all, or is a fixed file in the theme or a product description.

Because the CDN makes new copies at the requested width, the weight of your original upload matters less on Shopify than on a self-hosted site. A 6 MB original requested at 800 pixels wide is delivered as a much smaller 800 pixel file. The biggest wins therefore come from the theme and the admin, not from re-compressing originals.

Reading Shopify image addresses

View the source of a product page and look at the image addresses. They tell you which Liquid produced them and whether the CDN is being asked to resize.

In developer tools, the Network panel shows the format actually delivered in its Type column, which may be WebP even when the URL ends in .jpg, because the CDN negotiates the format.

Image code for modern Shopify themes

The current filters are image_url, which builds a CDN address for a given width or height, and image_tag, which turns that address into a complete <img> element. image_tag prints width and height, builds a srcset of smaller widths up to the one you requested, uses the image's stored alt text by default, and passes through extra attributes such as loading, fetchpriority and class. The older img_url and img_tag filters are deprecated.

A product gallery

{%- for media in product.media -%}
  {%- if media.media_type == 'image' -%}
    {%- liquid
      if forloop.first
        assign img_loading = 'eager'
        assign img_priority = 'high'
      else
        assign img_loading = 'lazy'
        assign img_priority = 'auto'
      endif
    -%}
    {{ media.preview_image
      | image_url: width: 1600
      | image_tag:
        widths: '400, 600, 800, 1200, 1600',
        sizes: '(min-width: 990px) 55vw, 100vw',
        loading: img_loading,
        fetchpriority: img_priority,
        alt: media.alt }}
  {%- endif -%}
{%- endfor -%}

Only the first media item is loaded eagerly with high priority, because it is usually the Largest Contentful Paint element on a product page. The rest wait until the visitor scrolls or swipes near them.

Replacing an old tag

{%- comment -%} Before: deprecated, fixed size, no srcset or dimensions {%- endcomment -%}
<img src="{{ product.featured_image | img_url: '1024x' }}" alt="{{ product.title }}">

{%- comment -%} After {%- endcomment -%}
{{ product.featured_image
  | image_url: width: 1200
  | image_tag: widths: '360, 540, 720, 900, 1200',
    sizes: '(min-width: 750px) 50vw, 100vw' }}

Notice the old tag also printed the product title as alt text on every image. The new version uses the alt text stored on the image itself, which you can make distinct for each photo.

Getting widths and sizes right

The largest width you request should cover the biggest the image is ever shown, allowing for high-density screens. A product image shown at about 700 CSS pixels on a desktop needs roughly 1400 pixels for a sharp result on a high-density screen; requesting 3000 wastes bytes on every desktop visit.

The sizes attribute is where Shopify themes most often go wrong. It tells the browser how wide the image will be displayed at each screen width, before the layout is known, so it can choose the right file from the srcset. If a collection grid shows four products per row on desktop but sizes says 100vw, the browser assumes each card image is full width and downloads a file roughly four times wider than needed.

• Full-width banner: 100vw is correct.
• Product gallery in a two-column layout: something like (min-width: 990px) 55vw, 100vw.
• Collection grid, four across on desktop and two on mobile: something like (min-width: 990px) 25vw, 50vw.

Measure the real width of the image in developer tools at a few screen sizes and write sizes to match. It does not need to be exact, but it should not be several times too large.

The fix, step by step

Variant images and galleries

Stores with colours or finishes often have the most image problems, because each variant adds photos and each photo needs its own alt text.

• Link each variant to its image in the product admin, so choosing a colour shows the right photo. In Liquid, the selected variant's image is available as product.selected_or_first_available_variant.featured_media, which lets the page load with the correct photo when a variant is chosen by URL.
• Check the variant switch script. When a visitor chooses a variant, theme JavaScript swaps the main image. Make sure it swaps the srcset as well as the src, or phones may download a full-size image on every change.
• Describe each variant photo. Alt text such as "Oak bedside table in dark walnut finish" helps both screen reader users and image search more than the product title repeated on every colour.
• Keep ratios consistent. Photograph variants at the same shape so the gallery does not change height when the image swaps. Layout shift on Shopify is covered in detail in the Shopify layout shift guide.

Images that bypass the resizing pipeline

Images in product descriptions and pages

Images inserted through the rich text editor are placed in the HTML with a fixed address and size, so they get no srcset and every visitor receives the same file. Keep description images modest in size before inserting them, set their alt text in the editor's image dialog, and for image-heavy content consider using theme sections or metafields instead, which go through image_url.

Images in the theme's assets folder

Files referenced with asset_url are delivered as uploaded. That is fine for small icons and SVG logos, but a large banner photo stored there is served at full size to every device. Move it to an image setting in the section, so the merchant can change it in the theme editor and Liquid can resize it.

Images added by apps

Review apps, upsell widgets and page builders sometimes insert their own images with no width, height or lazy-loading. Test pages with each app's block temporarily disabled in the theme editor to see which app adds the weight, then check the app's settings or contact its developer.

Keeping a Shopify store in good shape

• Run Theme Check before publishing theme changes, so deprecated filters and unsized images are caught early.
• Recheck after theme updates. Updating to a new theme version can overwrite your Liquid changes; keep a note of every file you edited.
• Add alt text as part of product setup, in the admin or the import CSV, so new products never go live without it.
• Keep content images out of descriptions where a section or metafield can do the job.
• Trial apps on a duplicate theme and run the audit before and after installing them.

For the wider picture of how images affect speed on Shopify, see the Shopify page speed guide, and for writing product photo alt text, the product images guide.