Description

The image_url filter returns a Cloudinary URL for an Image 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 <picture> source. To output a complete <img> element with a responsive srcset, use image_tag instead.

Property	Value
Return Type	string
Category	images
Available in	Storefront templates. Not available in POS templates.

```liquid

{{ product.image | image_url: width: 800, height: 600, crop: “fill” }} ```

The input must be an Image object. Any other input returns an empty string.

Options

Option	Default	Description
width	Original width	Width in pixels.
height	Original height	Height in pixels.
crop	fit	Cloudinary crop mode. See the crop modes table below. An unrecognized value falls back to fit.
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.

Sizing rules

• 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.
• No dimensions. The original width and height are used.
• 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.
• Maximum size. No dimension exceeds 5120 pixels.
• 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.

Images that are not hosted on Cloudinary are returned at their original URL, and the options are ignored. GIF and SVG images are not transformed.

Crop modes

Mode	Result
fit	Fits inside the box and keeps the aspect ratio.
limit	Like fit.
fill	Fills the box exactly and crops the overflow from the center.
scale	Stretches to the exact box, ignoring the aspect ratio.
pad	Fits inside the box and pads the remaining space.
crop	Cuts an exact box out of the original image without resizing it.
thumb	Generates a thumbnail cropped to the box.

Examples

A URL 400 pixels wide, with the height calculated from the aspect ratio:

```liquid

{{ product.image | image_url: width: 400 }} ```

A full-width banner cropped to a 16:9 box, used as a CSS background:

```liquid

<section class=”hero” style=”background-image: url(‘{{ article.hero_image | image_url: width: 1920, height: 1080, crop: “fill” }}’)”>

{{ article.title }}

</section> ```

A <picture> element that serves a square crop on small screens and a wide crop on larger ones:

```liquid

<source media="(max-width: 640px)" srcset="{{ product.image | image_url: width: 640, height: 640, crop: "fill" }}"> <img src="{{ product.image | image_url: width: 1200, height: 600, crop: "fill" }}" alt="{{ product.image.alt_text | default: product.name }}">

```