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.
Read more
- Vue.js Tutorial — A Guide on Prototyping Web Apps
- How to Create a Sticky Add to Cart Button On Scroll
- Introducing Online Store 2.0: What it Means For Developers
- How to Build a Shopify App: The Complete Guide
- An Overview of Liquid: Shopify's Templating Language
- How to Use Math Filters with Liquid
- How to Combat Image Cropping on Shopify Slideshow Sections
- 10 Top Questions About Developing Shopify Themes Answered
- Tips for an Efficient Shopify Theme Review Process
Do you have other Liquid examples on how to customize markup in themes? Share it with us in the comments below!