How to Customize the img Element in Shopify Themes

Products, collections, and blog posts typically contain images that are uploaded to a store as content. But how do we add images that are contained within and specific to a theme as part of the look and feel, such as background images, icons, logos and more?

In this article we’ll cover how we reference images from the assets directory that are part of the look and feel of your store, rather than the content itself. We’ll look at how to set appropriate alternative text using the img_tag filter, and how to include additional HTML attributes, like id, when adding images from the assets directory.

Getting started

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 are used for backgrounds, sprites, and branding elements.

Referencing these images in a theme is pretty straightforward. Let’s assume we have a logo.png for a company called “The Soap Store” in our assets directory. We can output this image in any template using the following Liquid syntax:

{{ 'logo.png' | asset_url | img_tag: 'The Soap Store' }}

This approach uses two Liquid filters to create a fully formed HTML img element. The first filter, asset_url, prepends the full path to the assets directory for the current store's theme. The second, img_tag filter uses this URL and creates an HTML img element, complete with alt attribute. If omitted, the alt attribute will have a value set to blank. The output looks something like this:

<img src="//cdn.shopify.com/s/files/1/0222/9076/t/10/assets/logo.png?796" alt="The Soap Store">

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 pushed out to the Shopify CDN. You’ll never worry about the location of your images, as the asset_url filter will work this out for you when the page is rendered. This approach also means that your themes are fully transferable from one store to another.

While we're on the subject of URLs, learn more about what a canonical URL is, and why they're so important.

You might also like: The Essential List of Resources for Shopify Theme Development.

A note on alternative text

Alt text, or “alternative text” as the long-form name suggests, is a written text description for an image on the web. It describes the image in order to help the reader understand what the image is about.

Without an alt attribute, your HTML markup is considered invalid and may result in an inconsistent user experience. That’s why if omitted, the alt attribute will have a value set to blank; this ensures that the output is still valid HTML.

You’ll notice in the example above we included the company name as the alternative text for the logo image, as opposed to just the word “Logo”. If an image itself contains text, such as a logo or a quote embedded within the image, the alt attribute value should be an exact match to the visible text.

For a more detailed explanation on alternative text, check out this great article by Scott Vinkle, front end developer and web accessibility advocate at Shopify.

You might also like: How to Manipulate Images with the img_url Filter.

Adding classes to the img element

In the example above we specified the alt attribute. It’s also possible to add an additional parameter that allows you to add class names to the class attribute on the img element. To add the class names of css--class1 and css--class2 we can add a second parameter to the img_tag filter:

{{ 'logo.png' | asset_url | img_tag: 'The Soap Store', 'css--class1 css--class2' }}

This would result in the following output:

<img src="//cdn.shopify.com/s/files/1/0222/9076/t/10/assets/logo.png?796" alt="The Soap Store" class="css--class1 css--class2">

Creating your own img tag for more control

There will of course be occasions where you need more control over the markup, for example when adding additional HTML attributes like id or data. By simply omitting the img_tag filter, we can write out the markup however we see fit.

In the example below, we can format the markup to add an id attribute to the img tag:

<img src="{{ 'logo.png' | asset_url }}" alt="The Soap Store" class="css--class1 css--class2" id="logo">

That’s all there is to it!

I hope you learned some new and interesting tricks, like how to use Liquid filters to generate markup output of images and how to add additional attributes to an img tag in Liquid. Keep in mind that you should always include appropriate alt text for accessibility purposes.

Do you have other Liquid examples on how to customize markup in themes? Share it with us in the comments below!