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' }}
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' }}
Similarly, specifying only a height would look like this:
{{ product | img_url: 'x450' }}
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:
- The original image was
450px
or greater on both axis - 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' }}
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 }}
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' }}
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.
Read more
- Introducing Online Store 2.0: What it Means For Developers
- How to Build a Shopify App: The Complete Guide
- Working with Product Variants When Building a Shopify Theme
- An Overview of Liquid: Shopify's Templating Language
- Using Placeholder Images for Products with the placeholder_svg_tag Filter
- Build Forms on Shopify: How to Use Liquid to Build Robust Forms for Shopify Themes
- How to work with Metafields when building Shopify themes
- How to Improve Custom Search in Your Clients' Storefronts
- Understanding Date Formats in Liquid and Shopify