--- title: "image_tag - Liquid Filter Reference" source: https://support.storeconnect.com/articles/image-tag-filter-reference type: article format: markdown site: StoreConnect Support — product and developer documentation for StoreConnect site_index: https://storeconnect.com/llms.txt docs_index: https://support.storeconnect.com/llms.txt note: Append .md to any page or article URL on this site to get its Markdown form. --- # image_tag - Liquid Filter Reference ## Description The `image_tag` filter turns an image into a complete `` element in one call. Given an [Image](image-liquid-object-reference) object, it builds a Cloudinary URL at the size you ask for, adds a responsive `srcset`, fills in the alt text from the media record, and sets `width`, `height`, `loading` and `decoding` so the browser can reserve space and load the image efficiently. | Property | Value | |----------|-------| | **Return Type** | string (HTML) | | **Category** | images | | **Available in** | Storefront templates. Not available in POS templates. | ```liquid {{ product.image | image_tag: width: 800, sizes: "(max-width: 640px) 100vw, 50vw" }} ``` The filter accepts two kinds of input: - **An Image object**, such as `product.image` or `article.hero_image`. The filter reads the media record to build the URL, fill in the alt text and dimensions, and generate a `srcset`. - **A URL string**, usually the output of [`image_url`](image-url-filter-reference). Without the media record, the filter emits only the attributes you pass, plus the default `loading` and `decoding` values. No alt text, dimensions or `srcset` are derived. Any other input returns an empty string. ## Options The `width`, `height`, `crop` and `quality` options work exactly as they do for [`image_url`](image-url-filter-reference): the image is never enlarged past the original, no dimension exceeds 5120 pixels, and a missing dimension is calculated from the aspect ratio. | Option | Default | Description | |--------|---------|-------------| | `width` | Original width | Width in pixels. | | `height` | Calculated from the aspect ratio | Height in pixels. | | `crop` | `fit` | Cloudinary crop mode: `fit`, `fill`, `scale`, `pad`, `crop`, `thumb` or `limit`. | | `quality` | `auto` | `auto`, `best`, `good`, `eco`, `low`, `none`, or a number from `1` to `100`. | | `alt` | The image's **Alt Text** | Alt text. With a URL string input, the default is empty. | | `class` | None | CSS classes. | | `id` | None | HTML `id`. | | `loading` | `lazy` | `lazy` or `eager`. | | `decoding` | `async` | `async`, `sync` or `auto`. | | `fetchpriority` | None | `high`, `low` or `auto`. | | `sizes` | None | The `sizes` attribute. Emitted only when the tag has a `srcset`. | | `widths` | The default width ladder | Comma-separated widths to build the `srcset` from, such as `"400,800,1200"`. `srcset_widths` is accepted as an alias. | | `srcset` | Generated | An explicit `srcset` string, output as written. Pass `srcset: nil` to leave the attribute off. | | `data-*`, `aria-*` | None | Passed through to the element, for example `data-zoom: "true"` or `aria-label: "Front view"`. | An unrecognized value for `loading`, `decoding`, `crop` or `fetchpriority` falls back to the default. Attributes other than those listed, including event handlers such as `onclick`, are never output, and every value is HTML-escaped. ## How the srcset is built For an Image object, `image_tag` generates a `srcset` automatically when all of these are true: - The image is hosted on Cloudinary and is not a GIF or SVG. - The media record has a stored width and height. - The crop is `fit` or `limit` (the aspect ratio is preserved). - `quality` is left at the default. The candidates come from a fixed ladder of widths: 320, 400, 512, 640, 800, 1024, 1280, 1600 and 2048 pixels. Widths larger than the original image are left out. When you pass `width`, the ladder stops at the first width that reaches twice that value, so a high-density screen can still pick a sharp image without the browser being offered anything larger. To control the candidates yourself, pass `widths`. This also works with an exact crop such as `fill`, and with a custom `quality`, where the default ladder is skipped. Each candidate keeps the crop and aspect ratio of the `src`. :::tip Always pass `sizes` with a responsive image. Without it, the browser assumes the image fills the full viewport width and downloads a larger file than it needs. ::: ## Width and height attributes The `width` and `height` attributes describe the image the browser receives, not the box you asked for. With `fit` or `limit`, a box that does not match the image's shape delivers a smaller image in one direction, and the attributes follow that delivered size. For example, a 1600 by 1200 image requested at `width: 800, height: 800` is delivered at 800 by 600, and the tag carries `width="800" height="600"`. Exact crops such as `fill` fill the box, so the attributes match the request. ## Examples A product card image that loads lazily and picks a size from the default ladder. The product image here is 1600 by 1200 pixels, with the alt text "Blue linen shirt": ```liquid {{ product.image | image_tag: width: 400, sizes: "(max-width: 640px) 50vw, 25vw", class: "product-card__image" }} ``` **Output** (URLs shortened): ```html Blue linen shirt ``` A hero image above the fold, cropped to an exact box, with explicit candidate widths and a high fetch priority: ```liquid {{ article.hero_image | image_tag: width: 1600, height: 600, crop: "fill", widths: "800,1200,1600", sizes: "100vw", loading: "eager", fetchpriority: "high", alt: article.title }} ``` An image with data and ARIA attributes for a gallery script: ```liquid {{ product.image | image_tag: width: 800, data-zoom: "true", aria-label: product.name }} ``` Chaining from `image_url`, for themes ported from Shopify: ```liquid {{ product.image | image_url: width: 800 | image_tag: alt: product.name, class: "hero" }} ``` This form has no `srcset` or dimensions unless you pass them, so prefer passing the Image object straight to `image_tag`. --- ## Follow StoreConnect - [Email Newsletter](https://storeconnect.com/c/lp-newsletter) - [LinkedIn Newsletter](https://www.linkedin.com/build-relation/newsletter-follow?entityUrn=7444956928444862464) - [YouTube](https://www.youtube.com/channel/UCngKdP2x8l1wcbAKW3tvU8g) - [LinkedIn](https://www.linkedin.com/company/storeconnect) - [X / Twitter](https://x.com/storeconnecthq) ## Popular Links - [Partners](https://storeconnect.com/partners) - [Become a Partner](https://storeconnect.com/become-a-partner) - [News](https://storeconnect.com/articles/news) - [Events](https://storeconnect.com/articles/events) - [Feature Comparison](https://storeconnect.com/how-we-compare) - [Download a free trial](https://appexchange.salesforce.com/appxListingDetail?listingId=a0N3A00000FMkeKUAT) - [Book a Demo](https://storeconnect.com/contact) ## Documentation - [Help documentation](https://support.storeconnect.com/help-documentation) - [AI agents](https://support.storeconnect.com/ai) - [Videos & tutorials](https://support.storeconnect.com/videos-tutorials) - [Developer reference](https://support.storeconnect.com/developer-reference) - [Release notes](https://support.storeconnect.com/release-notes) - [Troubleshooting](https://support.storeconnect.com/troubleshooting) - [Trust Center](https://trust.getstoreconnect.com/) - [Status Page](https://status.storeconnect.com/) ## Contact - info@getstoreconnect.com - US +1 415 745 3230 - AUS +61 2 8365 2308 100 S Ashley Dr, Suite 600-2461 Tampa FL 33602-600 USA Level 22, Sydney Place 180 George Street Sydney, NSW, 2000, AUS ## Machine-readable - [Site index for agents](https://storeconnect.com/llms.txt): curated map of the StoreConnect site in llms.txt format - [Documentation index for agents](https://support.storeconnect.com/llms.txt): full technical and product documentation map Every page and article on this site has a Markdown rendering: append `.md` to its URL. Continue in Markdown: [Help documentation](https://support.storeconnect.com/help-documentation.md) · [Developer reference](https://support.storeconnect.com/developer-reference.md) · [Videos & tutorials](https://support.storeconnect.com/videos-tutorials.md) · [Release notes](https://support.storeconnect.com/release-notes.md) --- StoreConnect Support — https://support.storeconnect.com/articles/image-tag-filter-reference