How to Manipulate Images with the img_url Filter

As Liquid evolves, more options are becoming available that will allow developers to unlock new potential for your custom themes. Liquid filters are simple but powerful methods for the output of objects and assets on a Shopify store.

In this post, we’ll look at how to use the img_url 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 its 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

In this post, we’ll focus on using the product object, with the img_url filter. Here’s a simple example:

{{ product.featured_image | img_url: '100x100' }}

In the example above, the img_url filter has a parameter of 100x100. As we’ll see soon, you can specify exact dimensions in pixels for any image's width and height.

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

{{ product.featured_image | img_url: '100x100' | img_tag }}

New parameters

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.

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

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

You might also like: Canonical URL: What Are They and Why Are They Important?

1. Size

Let’s begin by looking at how we can resize an image. In order to do this, we assign a numerical value, with a specific size in pixels, to the img_url. Here’s an example:

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

View generated image

In this way, you can specify exact dimensions in pixels for any image's width and height, up to a maximum of 4472x4472. If you don't include an image size, the filter returns a small (100x100) image.

Instead of using a numeric image size, some older themes use a named size as a parameter for img_url. This is why, on older themes, you might see a name, such as grande instead of a specific pixel range. These named size parameters have become deprecated in favor of the more customizable format where exact pixel numbers can be used.

The “names” mentioned above will of course work as they always have. However, using the numerical syntax now puts the control of the image dimensions in your hands.

The image's original aspect ratio will be preserved unless you crop the image. No matter what size you specify, an image can never be resized to be larger than its original dimensions.

In this case, the image will be no bigger than 450x450 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 450 pixels. In other words, all resizing is proportional unless you crop the image.

If you like, you can also specify only a width or only a height, and Shopify will calculate the other dimension based on the original image size, keeping the original image's aspect ratio. Here is an example of specifying only a width:

{{ product.featured_image | img_url: '450x' }}

View generated image

Similarly, specifying only a height would look like this:

{{ product | 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.

Valid options include:

• top
• center
• bottom
• left
• right

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_url filter 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.

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 aren’t possible.

You might also like: Using Responsive Images to Decrease Page Loading Times.

Caching

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

Unlocking responsive imagery

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 start offering the most appropriate image for both screen size, resolution, and bandwidth.