Image Transformations

Fluid serves theme images through ImageKit, which can resize, crop, and reformat images on the fly. The image_url and img_url Liquid filters turn transformation options into an ImageKit URL, so a layout can request exactly the rendition it needs instead of loading the full-size original.

{{ section.settings.image | image_url: "w-600,c-at_max,f-auto,q-80" }}

https://cdn.example.com/products/shirt.jpg
→ https://cdn.example.com/tr:w-600,c-at_max,f-auto,q-80/products/shirt.jpg

The filters

image_url and img_url behave identically. Both take an image plus one or more transformation options:

• Input — an image object (such as section.settings.image or product.image), a hash with a url or src key, or a plain URL string.
• Output — the image URL with an ImageKit transformation segment (tr:…) inserted, or the URL unchanged when there is nothing to apply.

img_url is the older, Shopify-style name; image_url is preferred for new themes. They are interchangeable on this engine.

Specifying transformations

Pass transformations as a raw ImageKit string, as named parameters, or both.

Raw ImageKit transform string

Pass any ImageKit transformation string. Tokens are comma-separated code-value pairs; whitespace around the commas is ignored.

{{ image | image_url: "w-600,c-at_max,f-auto,q-80" }}
{{ image | image_url: "w-600, c-at_max, f-auto, q-80" }}
{{ image | image_url: "n-product_card" }}

The first two lines produce the same result (whitespace is ignored); the third applies a named transformation defined in the ImageKit dashboard. This is the most capable option — it supports the full ImageKit vocabulary (focus, blur, effects, overlays, named transformations, and more). See ImageKit's image transformation reference for every parameter.

Named parameters

For common cases, pass named parameters instead of remembering ImageKit codes:

{{ image | image_url: width: 600, height: 400, quality: 80, format: 'auto' }}

→ …/tr:w-600,h-400,q-80,f-auto/…

Notes:

• width, height, and format mirror Shopify's image_url filter. quality is ImageKit-specific (Shopify has no quality parameter on this filter) and is included as a convenience.
• crop accepts top, bottom, left, right, or center and maps to ImageKit focus (fo-). Focus only takes effect alongside a resize, so crop is ignored unless a width or height is also given.
• Anything not covered by a named parameter (custom crop modes, blur, effects, and so on) is available through the raw transform string.

Combining both

A raw string and named parameters can be used in the same call:

{{ image | image_url: "f-auto,q-80", width: 600 }}

→ …/tr:f-auto,q-80,w-600/…

Behavior

• Only ImageKit images are transformed. If the resolved URL points to a custom or third-party host (not Fluid's ImageKit), it is returned unchanged and the transformation options are ignored.
• An existing transformation is replaced. If the URL already contains a tr: segment, it is swapped for the new one.
• No options means no change. Calling the filter with no transformation options returns the resolved URL as-is.

Migrating from Shopify size strings

Shopify's img_url accepts size strings such as '300x200', 'medium', or 'master'. These are not supported here — they pass through unchanged, so the image is returned at its original size. Use ImageKit syntax instead:

Examples

Responsive product card with a 2× rendition:

<img
  src="{{ product.image | image_url: 'w-600,c-at_max,f-auto,q-80' }}"
  srcset="{{ product.image | image_url: 'w-600,c-at_max,f-auto,q-80' }} 1x,
          {{ product.image | image_url: 'w-1200,c-at_max,f-auto,q-80' }} 2x"
  alt="{{ product.title | escape }}"
  loading="lazy"
>

Section setting with an editor-controlled width:

<img src="{{ section.settings.image | image_url: transform }}" alt="" loading="lazy">

Named transformation preset (defined in the ImageKit dashboard):

{{ product.image | image_url: 'n-product_card' }}

Common ImageKit transforms

A quick reference for the raw string — see ImageKit's documentation for the full list:

See also

• Build Fluid Themes
• Template Variables