{"title":"image_url - Liquid Filter Reference","slug":"image-url-filter-reference","url":"https://support.storeconnect.com/articles/image-url-filter-reference","url_markdown":"https://support.storeconnect.com/articles/image-url-filter-reference.md","subtitle":null,"summary":"Get a Cloudinary URL for a StoreConnect image at a custom width, height, crop mode and quality. Use it when you need the URL itself, for example in a background image or a hand-built srcset.","type":"Developer_Documentation","video_url":"","keywords":"liquid, filters, image_url, image size, crop, quality, cloudinary, responsive images, theme, storeconnect","last_modified":"2026-11-04T01:42:14+0000","body_markdown":"## Description\n\nThe `image_url` filter returns a Cloudinary URL for an [Image](image-liquid-object-reference) object at the size, crop and quality you ask for. Use it when you need a URL rather than markup, such as a CSS background image or a `\u003cpicture\u003e` source. To output a complete `\u003cimg\u003e` element with a responsive `srcset`, use [`image_tag`](image-tag-filter-reference) instead.\n\n| Property | Value |\n|----------|-------|\n| **Return Type** | string |\n| **Category** | images |\n| **Available in** | Storefront templates. Not available in POS templates. |\n\n\n```liquid\n\n{{ product.image | image_url: width: 800, height: 600, crop: \"fill\" }}\n```\n\n\nThe input must be an Image object. Any other input returns an empty string.\n\n## Options\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `width` | Original width | Width in pixels. |\n| `height` | Original height | Height in pixels. |\n| `crop` | `fit` | Cloudinary crop mode. See the crop modes table below. An unrecognized value falls back to `fit`. |\n| `quality` | `auto` | `auto`, `best`, `good`, `eco` or `low` for automatic quality at that level, `none` to turn automatic quality off, or a number from `1` to `100`. |\n\n### Sizing rules\n\n- **One dimension.** When you pass only `width` or only `height`, and the media record has a stored width and height, the other dimension is calculated from the aspect ratio.\n- **No dimensions.** The original width and height are used.\n- **Never enlarged.** A requested size larger than the original is reduced to the original size. With an exact crop such as `fill`, the whole box is scaled down together, so the crop keeps the shape you asked for.\n- **Maximum size.** No dimension exceeds 5120 pixels.\n- **No stored dimensions.** When the media record has no width or height, the filter passes on only the dimensions you give, and Cloudinary calculates the rest. With no dimensions at all, the original image is returned, still optimized for format and quality.\n\nImages that are not hosted on Cloudinary are returned at their original URL, and the options are ignored. GIF and SVG images are not transformed.\n\n### Crop modes\n\n| Mode | Result |\n|------|--------|\n| `fit` | Fits inside the box and keeps the aspect ratio. |\n| `limit` | Like `fit`. |\n| `fill` | Fills the box exactly and crops the overflow from the center. |\n| `scale` | Stretches to the exact box, ignoring the aspect ratio. |\n| `pad` | Fits inside the box and pads the remaining space. |\n| `crop` | Cuts an exact box out of the original image without resizing it. |\n| `thumb` | Generates a thumbnail cropped to the box. |\n\n## Examples\n\nA URL 400 pixels wide, with the height calculated from the aspect ratio:\n\n\n```liquid\n\n{{ product.image | image_url: width: 400 }}\n```\n\n\nA full-width banner cropped to a 16:9 box, used as a CSS background:\n\n\n```liquid\n\n\u003csection class=\"hero\" style=\"background-image: url('{{ article.hero_image | image_url: width: 1920, height: 1080, crop: \"fill\" }}')\"\u003e\n  \u003ch1\u003e{{ article.title }}\u003c/h1\u003e\n\u003c/section\u003e\n```\n\n\nA `\u003cpicture\u003e` element that serves a square crop on small screens and a wide crop on larger ones:\n\n\n```liquid\n\n\u003cpicture\u003e\n  \u003csource media=\"(max-width: 640px)\" srcset=\"{{ product.image | image_url: width: 640, height: 640, crop: \"fill\" }}\"\u003e\n  \u003cimg src=\"{{ product.image | image_url: width: 1200, height: 600, crop: \"fill\" }}\" alt=\"{{ product.image.alt_text | default: product.name }}\"\u003e\n\u003c/picture\u003e\n```\n"}