The img_url Filter Just Got 10x Better

The img_url Filter Just Got 10x Better

The img_url Filter Just Got 10x Better: 2016In a previous tutorial, we took a look at the very useful img_tag filter. Closely linked to this is the equally useful img_url filter. In this article, we’ll look at how to use this Liquid filter and examine the recently added parameters that allow you to manipulate images within Shopify in new and exciting ways.

Let’s begin by looking at the function of the img_url filter. In it’s basic form, it will return the URL of an image. In order to do this, you need to pass in a mandatory size parameter. It’s also quite a versatile filter as it can be used with the following objects, which have images associated with them:

  • product
  • variant
  • line item
  • collection
  • article
  • Image

We’ll focus on using the product object in this article. Here’s an example:

{{ product.featured_image | img_url: 'small' }}

When used in a product.liquid template this would result in a URL similar to this image.

In the example above, the img_url filter has a parameter of "small". This value corresponds to a particular size of image that was created automatically by Shopify, after it was uploaded via the admin.

In the case of "small", the image will be no bigger than 100x100 pixels. If you upload a square image, it will be perfectly resized. However, if your original image is longer on one side than the other, Shopify will resize accordingly so that the longest side will be 100 pixels. In other words, all resizing is proportional.

Here’s the list of sizes with their corresponding image names:

16 × 16


32 × 32


50 × 50


100 × 100


160 × 160


240 × 240


480 × 480


600 × 600


1024 × 1024


2048 × 2048


Largest image


You can also chain the img_url filter with the img_tag filter to output the full img element:

{{ product.featured_image | img_url: 'small' | img_tag }}

So far, we’ve looked at the basic function of the img_url filter. Until recently there wasn’t much more you could do with it. However, all that changed in July 2016 when a new set of parameters were added making it possible to resize and crop images from within your template files.

You might also like: 10 Top Questions About Developing Shopify Themes Answered

New Parameters

Before moving on, it’s worth noting that the following techniques can be used with a range of filters in addition to img_url. They are:

  • product_img_url
  • collection_img_url
  • article_img_url

I’ll use img_url in all the following examples, but I want to highlight that the techniques work with the three other filters, too.

1. Size

Let’s begin by looking at how we can resize an image. In order to do this, we replace the image “name” with a specific size in pixels. Here’s an example:

{{ product.featured_image | img_url: '450x450’ }}

View generated image

The “names” mentioned above will of course work as they always have. However, using the above syntax now puts the control of the image dimensions in your hands. In this example, we have specified both the width and height (in that order).

You can also specify only a width, or only a height.

Width only: {{ product.featured_image | img_url: '450x’ }}

View generated image

Height only: {{ product.featured_image | img_url: 'x450’ }}

View generated image

When only specifying a single value, Shopify will calculate the other dimension based on the original image size, keeping the original image's aspect ratio intact.

Going back to our original example, you might think that it would result in a 450x450 version of your image being rendered. This, however, isn’t always the case.

This request would result in a perfect square, only if both of the following conditions are met:

  1. The original image was 450px or greater on both axis
  2. Both sides are of the same length

If both conditions are true then a 450x450 square image would be rendered. If not, Shopify will resize it using the same logic as if you’ve specified only height or width. The longest side wins out in this situation and is scaled accordingly.

2. Crop

Thankfully creating perfect squares won’t require you to upload square images. All that it requires is the addition of another new parameter called crop. You specify a crop parameter to ensure that the resulting image's dimensions match the requested dimensions. If the entire image won't fit in your requested dimensions, the crop parameter specifies which part of the image to show. There are three valid options:

  • top
  • center
  • bottom

Here’s an example building on the one we discussed earlier:

{{ product.featured_image | img_url: '450x450’, crop: ‘center’ }}

View generated image

3. Scale

As well as dimensions, we can also request a certain pixel density using the scale parameter. The two valid options are:

  • 2
  • 3

You can simply add this as another argument to the img_urlfilter as follows:

{ product.featured_image | img_url: '450x450’, crop: ‘center’, scale: 2 }}

View generated image

This would result in a resized image of 900x900 pixels. Again, this will only be scaled up if the original image is large enough. If it isn’t the case, the closest image in size will be returned.

You might also like: How to Use Liquid's "case/when" Control Tags in Shopify Themes

4. Format

There’s one final parameter you can add, which is format. Valid options for this are:

  • jpg
  • pjpg

Here’s an example incorporating format:

{{ product.featured_image | img_url: '450x450’, crop: ‘center’, scale: 2, format: ‘pjpg’ }}

View generated image

This would result in the image being rendered as a progressive JPG — these load as a full-sized image with gradually increasing quality, as opposed to a top-to-bottom load. It’s a great option to have depending on your needs.

Shopify can do the following format conversions for you:

  • PNG to JPG
  • PNG to PJPG
  • JPG to PJPG

It's not practical to convert a lossy image format like JPG to a lossless one like PNG, so those conversions are not possible.


Finally, it’s worth noting that once the requested image has been created it will be cached and made available on the Shopify CDN. Consequently, there’s no need to worry about the image being created every time your template is rendered.


Thanks to these new parameters it’s now possible to implement responsive image techniques in your templates. Whether you want to start using the srcset and sizes attributes, or the picture element, you can really start offering the most appropriate image for both screen size, resolution, and bandwidth.

You might also like: Creating Useful CSS Hooks in Liquid

About the Author

Keir is based in the UK and works on the Partner Community Team at Shopify. You'll often find him at conferences and running workshops on Shopify theme building. You can subscribe to his newsletter, read his latest articles on his blog, listen to his podcast, and follow him on Twitter.

Grow your business with the Shopify Partner Program

Learn more