---
title: "Liquid filters: image_url"
description: Returns the [CDN URL](/themes/best-practices/performance/platform#shopify-cdn) for an image.
api_name: liquid
source_url:
  html: https://shopify.dev/docs/api/liquid/filters/image_url
  md: https://shopify.dev/docs/api/liquid/filters/image_url.md
---

# image\_​url

```oobleck
variable | image_url: width: number, height: number
```

returns [string](https://shopify.dev/docs/api/liquid/basics#string)

Returns the [CDN URL](https://shopify.dev/themes/best-practices/performance/platform#shopify-cdn) for an image.

You can use the `image_url` filter on the following objects, as well as their `src` property:

* [`article`](https://shopify.dev/docs/api/liquid/objects/article)
* [`collection`](https://shopify.dev/docs/api/liquid/objects/collection)
* [`image`](https://shopify.dev/docs/api/liquid/objects/image)
* [`line_item`](https://shopify.dev/docs/api/liquid/objects/line_item)
* [`product`](https://shopify.dev/docs/api/liquid/objects/product)
* [`variant`](https://shopify.dev/docs/api/liquid/objects/variant)
* [`country`](https://shopify.dev/docs/api/liquid/objects/country)

***

Caution

You need to specify either a [`width`](https://shopify.dev/docs/api/liquid/filters/image_url#image_url-width) or [`height`](https://shopify.dev/docs/api/liquid/filters/image_url#image_url-height) parameter. If neither are specified, then an error is returned.

***

***

Note

Regardless of the specified dimensions, an image can never be resized to be larger than its original dimensions.

***

```liquid
{{ product | image_url: width: 450 }}
```

##### Code

```
{{ product | image_url: width: 450 }}
```

## Output

```html
//polinas-potent-potions.myshopify.com/cdn/shop/files/science-beakers-blue-light-new.jpg?v=1683744744&width=450
```

### width

```oobleck
variable | image_url: width: number
```

Specify the width of the image up to a maximum of `5760px`. If only the width is specified, then the height is automatically calculated based on the image's dimensions.

```liquid
{{ product | image_url: width: 450 }}
```

##### Code

```
{{ product | image_url: width: 450 }}
```

## Output

```html
//polinas-potent-potions.myshopify.com/cdn/shop/files/science-beakers-blue-light-new.jpg?v=1683744744&width=450
```

### height

```oobleck
variable | image_url: height: number
```

Specify the height of the image up to a maximum of `5760px`. If only the height is specified, then the width is automatically calculated based on the image's dimensions.

```liquid
{{ product | image_url: height: 450 }}
```

##### Code

```
{{ product | image_url: height: 450 }}
```

## Output

```html
//polinas-potent-potions.myshopify.com/cdn/shop/files/science-beakers-blue-light-new.jpg?height=450&v=1683744744
```

### crop

```oobleck
variable | image_url: crop: string
```

Specify which part of the image to show if the specified dimensions result in an aspect ratio that differs from the original. You can use the following values:

* `top`
* `center`
* `bottom`
* `left`
* `right`
* `region`

The default value is `center`.

When using the `region` crop mode, the starting point for the crop is defined by `crop_left` and `crop_top` and extends to the `crop_width` and `crop_height`. Optionally, to resize the region extracted by the crop, use the `width` and `height` parameters.

***

Note

Country flags are SVG images and can only be cropped if a value for `format` is also provided.

***

```liquid
{{ product | image_url: width: 400, height: 400, crop: 'bottom' }}


{{ product | image_url: crop: 'region', crop_left: 32, crop_top: 32, crop_width: 512, crop_height: 512 }}


{{ product | image_url: crop: 'region', width: 100, height: 100, crop_left: 32, crop_top: 32, crop_width: 512, crop_height: 512 }}
```

##### Code

```
{{ product | image_url: width: 400, height: 400, crop: 'bottom' }}

{{ product | image_url: crop: 'region', crop_left: 32, crop_top: 32, crop_width: 512, crop_height: 512 }}

{{ product | image_url: crop: 'region', width: 100, height: 100, crop_left: 32, crop_top: 32, crop_width: 512, crop_height: 512 }}
```

## Output

```html
//polinas-potent-potions.myshopify.com/cdn/shop/files/science-beakers-blue-light-new.jpg?crop=bottom&height=400&v=1683744744&width=400


//polinas-potent-potions.myshopify.com/cdn/shop/files/science-beakers-blue-light-new.jpg?crop=region&crop_height=512&crop_left=32&crop_top=32&crop_width=512&v=1683744744


//polinas-potent-potions.myshopify.com/cdn/shop/files/science-beakers-blue-light-new.jpg?crop=region&crop_height=512&crop_left=32&crop_top=32&crop_width=512&height=100&v=1683744744&width=100
```

### format

```oobleck
variable | image_url: format: string
```

Specify which file format to use for the image. The valid formats are `pjpg` and `jpg`.

It's not practical to convert a lossy image format, like `jpg`, to a lossless image format, like `png`, so Shopify can do only the following conversions:

* `png` to `jpg`
* `png` to `pjpg`
* `jpg` to `pjpg`

***

Note

Shopify automatically detects which image formats are supported by the client (e.g. `WebP`, `AVIF`, etc.) and selects a file format for optimal quality and file size. When a format is specified, Shopify takes into account the features (e.g. progressive, alpha channel) of the specified file format when making the final automatic format selection. To learn more, visit <https://cdn.shopify.com/>.

***

```liquid
{{ product | image_url: width: 450, format: 'pjpg' }}
```

##### Code

```
{{ product | image_url: width: 450, format: 'pjpg' }}
```

## Output

```html
//polinas-potent-potions.myshopify.com/cdn/shop/files/science-beakers-blue-light-new.jpg?format=pjpg&v=1683744744&width=450
```

### pad\_color

```oobleck
variable | image_url: pad_color: string
```

Specify a color to pad the image if the specified dimensions result in an aspect ratio that differs from the original. The color must be in hexadecimal format (`hex3` or `hex6`).

```liquid
{{ product | image_url: width: 400, height: 400, pad_color: '000' }}
```

##### Code

```
{{ product | image_url: width: 400, height: 400, pad_color: '000' }}
```

## Output

```html
//polinas-potent-potions.myshopify.com/cdn/shop/files/science-beakers-blue-light-new.jpg?height=400&pad_color=000&v=1683744744&width=400
```