When starting out with a new platform, such as Shopify, there’s a lot to learn. Whilst Liquid, the template language used in Shopify themes, is very readable and easy to get started with, one area of Shopify development which can often cause confusion for new theme developers is images. I believe the main reason for this lies with understanding the “type” of image that you encounter within a Shopify theme. Over the course of this article we’ll examine each different type of image and how to use them within a Shopify theme.
If you are new to Liquid my three part series will give you a solid grounding and will be helpful as you follow along. If you are new to Shopify you can experiment with any of these techniques using a free development store. In order to create a development store sign up to the free Shopify Partner program.
Image Types
There are four types of images in a Shopify theme. You’ll work with each of them across a theme, so it’s important to understand the differences between them. Let’s examine each one in turn:
-
Theme images: these are stored within a theme’s
assetsfolder and are specific to that theme. These are usually added to the theme by a theme developer. - Product images: these images are specific to a store and uploaded via the Shopify admin for each product.
- Collection images: a single image assigned to represent a collection which is uploaded via the Shopify admin.
- Article images: a single image assigned to represent a blog article which is uploaded via the article edit page in the Shopify admin.
It’s important to note that product, collection and article images are all linked directly to the store. If you change the store’s theme these images will remain in place and will work with any given theme that references them.
1. Theme Images
Let’s begin by looking at theme images. When creating a Shopify theme you can add any number of images, in any format and at any size to the assets folder within your theme directory. Typically these images can be used for backgrounds, sprites, and branding elements.
Referencing these images in a theme is very straightforward. Let’s assume we have a logo.png in our assets folder; we can output it in any template using the following Liquid syntax:
{{ 'logo.png' | asset_url | img_tag: 'Logo' }}
This approach uses two Liquid filters to create a fully formed HTML img element. The first, asset_url, prepends the full path to the assets folder for the current store’s theme. The second, img_tag, takes this and creates an HTML img element complete with alt attribute. If omitted the alt attribute will be blank. Here’s the end result:
<img src="//cdn.shopify.com/s/files/1/0222/9076/t/10/assets/logo.png?796" alt="Logo">
Location, Location, Location
You’ll notice that the src attribute references the Shopify CDN (Content Delivery Network). Every image that you add, regardless of its type, will be distributed to the CDN. This helps ensure fast delivery of your store’s images to the customer.
Unlike self hosted image files you have no way of knowing the exact server location for your image files. Luckily, you don’t need to worry about this as the Shopify specific asset_url Liquid filter will provide the path for you when your page is rendered.
Abstracting the full server path away to a filter also means that your themes are fully transferable from one store to another. The correct URL gets included depending on the theme and the store being viewed.
Adding Classes to the img Element
In the example above we added the alt attribute via the img_tag filter. It’s also possible to add a further parameter which allows you to add classes to the img element. Here’s our code refactored:
{{ 'logo.png' | asset_url | img_tag: 'Logo', 'cssclass1 cssclass2' }}
This would result in the following output:
<img src="//cdn.shopify.com/s/files/1/0222/9076/t/10/assets/logo.png?796" alt="Logo" class="cssclass1 cssclass2">
More Control
There will of course be occasions where you need a little more control over your HTML. By omitting the img_tag filter we can build up our markup as we wish.
Here’s an approach which would allow you to add your own attributes such as id:
<img src="{{ 'logo.png' | asset_url }}" alt="Logo" class="cssclass1 cssclass2" id="logo">
Referencing Images in CSS and JavaScript
It’s also pretty easy to use these assets in both CSS and JavaScript files. In order to do this append .liquid (e.g. styles.css.liquid) to a CSS or JavaScript file in your assets folder and reference the image, in your CSS file, using the same Liquid code we used above:
body { background: url({{ 'logo.png' | asset_url }}) repeat-x top left; }
Theme images are relatively straightforward. As long as you understand how to use asset_url you can choose whether or not to add the extra img_tag filter or build up the img element yourself.
Product, Collection and Article Images
Whilst we have full control over our theme images we are at the mercy of store owners when it comes to product images. Thankfully Shopify goes a long way to helping us regain that control. Let’s begin by looking at what happens when a merchant uploads an image in the Shopify admin.
Each time a product, collection, or article image is uploaded Shopify takes that image and automatically resizes it into a number of predefined sizes. These images are “namespaced” so that we can easily reference them in our themes.
Here’s the list of sizes with their corresponding image names:
| 16 × 16 | pico |
| 32 × 32 | icon |
| 50 × 50 | thumb |
| 100 × 100 | small |
| 160 × 160 | compact |
| 240 × 240 | medium |
| 480 × 480 | large |
| 600 × 600 | grande |
| 1024 × 1024 | 1024×1024 |
| 2048 × 2048 | 2048×2048 |
| Largest image | master |
Automatic Resizing
The values above specify the “maximum” bounds of an image size. All resized images will keep their aspect ratio and will be scaled accordingly.
This could mean that a “medium” picture has a width of 240px but a height of only 190px and likewise a height of 240px but a width of 80px. It’s for this reason most theme developers request that their clients upload square images as they will be more predictable.
The “master” image size will always track the largest size available from the server. Currently this is 2048px × 2048px. If you upload an image larger than 2048px wide you won’t have access to its original form.
It’s also worth noting that the originally uploaded product image will never be scaled up in size. If you upload a tiny image, it will remain tiny. You can of course reference the image by using any of the above image names. However, note that if you request a size that wasn’t possible to create then you will be served the closest available size.
Also bare in mind that if manipulated with CSS (e.g. width: 100%) the image may be scaled up and may become pixelated (depending on its format). When working with clients encourage them to upload high resolution square images where possible.
Finally it’s worth remembering that we don’t have access to product images in our theme’s folder. They are stored on the Shopify CDN and remain attached to the store regardless of the theme that is applied.
2. Displaying Product Images
Unlike theme images product images do not make use of asset_url. In order to output a product image we can make use of the img_url Liquid filter instead. This is due to the fact that product images are related to the store and not part of the theme’s assets.
img_url returns the URL of an image and accepts an image size as a parameter. It can be used on the following Liquid objects:
- product
- variant
- line item
- collection
Using the img_url filter is as follows:
{{ product | img_url: 'small' }} {{ variant | img_url: 'small' }} {{ line_item | img_url: 'small' }} {{ collection | img_url: 'small' }}
Each of these will return the fully qualified URL to the image stored on the Shopify CDN.
To demonstrate let’s have a look at some example Liquid code from a typical product.liquid template. As this particular template has access to the product variable all of these examples will work. However, please note that they won’t work as expected in other templates.
In this first example the value of image will represent each image in the collection and have a different value through each iteration of our Liquid loop. This variable can be named however you see fit; I am using image as it contextually it makes sense.
{% for image in product.images %} <img src="{{ image | img_url: 'grande' }}"> {% endfor %}
Once you have been working with themes for sometime you might notice other filters being used in relation to product images. Here are some alternatives that could be used in our example above, each of which would have the same output:
<img src="{{ image.src | img_url: 'grande' }}"> <img src="{{ image | product_img_url: 'grande' }}">
It’s entirely up to you which you choose to use. If you prefer one method over another you can always leave a comment using {% comment %}…{% endcomment %} explaining your decision. This is especially useful when collaborating on themes.
Displaying product variant images
In addition to product images it’s also possible to display images relating to the products variants. A variant can be explained as a variation of the product. Let’s say we have a t-shirt with a particular print on it. This t-shirt may come in green, blue and red. Whilst the print stays the same the colour of the t-shirt itself is different. It’s still the same product, but we have chosen to enable the customer to pick from certain options. Often these will be size and colour.
Variants can also have their own price and inventory level. It’s possible to associate a particular image to each variant–in addition to the main product images. If your theme uses variant images you can display them in the following way in the product.liquid template:
{% for variant in product.variants %} {% if variant.image %} <img src="{{ variant | img_url: 'small' }}"> {% endif %} {% endfor %}
alt Attribute
If you wish to add the alt attribute to your output you can do so as follows:
{% for image in product.images %} <img src="{{ image | img_url: 'grande' }}" alt="{{ image.alt }}"> {% endfor %}
This will output the alt text entered in the Shopify admin, or blank if nothing was entered. Alternatively, you could do the following if you choose to use the img_tag filter:
{{ image | img_url: 'grande' | img_tag: image.alt }}
Featured Images
In our above example we used a Liquid loop to access each of the images associated with a product in turn. If the product had one image we’d output one image, if it had ten associated with it the loop would output ten images.
In Shopify the first image listed in the admin is also known as the “featured image”. Thankfully outputting the “featured image” is nice and straightforward and doesn’t require a loop. Here’s an example that would work in the product.liquid template:
<img src="{{ product.featured_image | product_img_url: 'grande' }}" alt="{{ product.featured_image.alt }}">
As always there are alternative ways you can achieve this, including:
<img src="{{ product | img_url: 'grande' }}"> <img src="{{ product.images.first | img_url: 'grande' }}"> <img src="{{ product.images[0] | img_url: 'grande' }}">
You can also extend the syntax to include the alt attribute in the second and third examples:
<img src="{{ product.images.first | img_url: 'grande' }}" alt="{{ product.images.first.alt }}"> <img src="{{ product.images[0] | img_url: 'grande' }}" alt="{{ product.images[0].alt }}" >
3. Collection Images
I often describe a collection in Shopify as a logical grouping of products. For example it could be t-shirts, jeans, and dresses for an apparel store. A product can sit in zero, one, or many collections, allowing for easy categorisation and discovery.
Often, merchants will wish to include a page on their store detailing all of their available collections. The template that makes this possible in Shopify is list-collections.liquid. Here’s an example of how you can loop over every collection and output the image associated with it from within that template:
{% for collection in collections %} {{ collection.image | img_url: 'compact' | img_tag: alt: collection.title }} {% endfor %}
You could extend this example further to ensure that you catered for the situation where a collection image hadn’t been added:
{% for collection in collections %} {% if collection.image %} {{ collection.image.src | img_url: 'medium'| img_tag: collection.title }} {% else %} {{ 'collection-image-default.png' | asset_url | img_tag }} {% endif %} {% endfor %}
In this instance we are using a theme image in place of the collection image. This will only be rendered if there is not an associated collection image. In order for this to work as intended you’ll need to ensure there is an image titled collection-image-default.png within your theme’s assets folder.
4. Article Images
Article images function in much the same way as product and collection images. Here’s an example:
{% if article.image %} {{ article | img_url: 'medium' | img_tag: article.title }} {% endif %}
If the article has an associated image then it will be displayed and given the alt attribute of the article’s title. There are a few ways collection and article images can come in useful:
- To create a grid of images in a listing page
- To use as background images which you can overlay text
Images Uploaded via “Customise Theme”
The final piece of the puzzle involves images uploaded via the “Customise Theme” option.
Every theme has a config folder. In it you’ll find a file called settings_schema.json. This file helps us generate an admin interface that allows merchants to add data such as text, boolean values (true/false), select fonts, upload images and much more. We are able to define these interface elements using JSON.
To enable an image upload you need to add a new element to the settings_schema.json file in the following format:
{ "type": "image", "id": "logo.png", "label": "Text", "max-width": 480, "max-height": 200, "info": "Text" }
Here’s an example based on adding a logo for the store:
{ "type": "image", "id": "shop_logo.png", "label": "Shop logo", "max-width": 480, "max-height": 200, }
Images uploaded through the “Customize Theme” page are added to the theme’s assets folder. As such I didn’t include them as a separate image type at the beginning of the article.
The image file is saved with a name and format which matches the id attribute regardless of the file’s original name or format. For example image.jpg file would be saved as shop_logo.png. Shopify will attempt to convert the uploaded file to the appropriate format (.png) before saving it. If Shopify is unable to convert the file to a .png file, the user will receive an error message in the admin.
You’ll notice that the input type is image which results in an upload button appearing in the browser. You can also specify a maximum height and width for an image upload by using data attributes. Shopify will then maintain the aspect ratio of the uploaded image while constraining it to those maximum dimensions.
Referencing images added via “Customise Theme” is done in the same way as all other theme images:
{{ 'logo.png' | asset_url | img_tag: 'Logo' }}
Name Spacing Customise Theme Uploads
One thing you might wish to consider is using the id attribute to “namespace” your theme setting uploads. This way they are easy to spot in the assets folder as they will be grouped together. It also helps accidentally overwriting files that you add into your theme.
I often use the ct- prefix as follows:
{ "type": "image", "id": "ct-shop_logo.png", "label": "Shop logo", "max-width": 480, "max-height": 200, }
Cropped Square Images
In the middle of 2015 Jason Bowman noticed that the Shopify checkout was displaying cropped square images. You can read about his discovery on his Freak Design blog.
Jason’s investigations led him to discover that all the checkout images were appended with _cropped. Here’s an example:
product-cropping-test-001_1024x1024.png
when cropped becomes:
product-cropping-test-001_1024x1024_cropped.png
The cropping works for all sizes except Master. In order to use cropped images we add _cropped to our img_tag filter. Here’s an example for a product featured image:
{{ product.featured_image | product_img_url: "medium_cropped" }}
At the time of writing this is undocumented so there’s always the possibility it may change, but I wanted to include it.
Final Thoughts
We’ve covered a lot of ground in this article but hopefully it’s shown you how flexible Shopify is when it comes to working with images in a theme.
Images are an integral part of any ecommerce store. Understanding how images are managed and manipulated in a Shopify theme is an important part of learning Liquid and the Shopify platform.
Hopefully you’ll agree that the tools within the Shopify platform and Liquid allow you a lot of flexibility when it comes to working with images in your themes.
