Image Tag HTML Objects

When you are working with images in your templates you will usually be working with an HTML Object. An example scenario would be displaying images for gallery items, store products, collection widgets or content layout images. Pretty much any time you would have an array of image information that array is actually an HTML Object.

The purpose of the HTML Object is to allow you to add or change the attributes for the image tag before outputting the image tag. Instead of having to manually build out the image tag just to set a custom alt text or class value you can set the attribute value and then simply output the image tag. This helps with readability and is often easier to write.

Instead of doing this:

now you can set the alt text and then simply output the code:

{% set image.alt = 'My Alt Text' %}
{{ image.tag }}

Available image attributes

Typically the following image attributes are available for you to set or change values:

alt
cdnVersion
class
height
loading
src
width

'class' and 'alt' may not always have values.

The cdnVersion attribute isn't output in the HTML. It's used to turn on or off CDN versioning for the individual image.

You can also set any valid HTML attribute on the image tag such as 'title' or 'data' attributes.

{% set image.title = 'My image title' %}
{% do image.set('data-custom', 'Data value') %}

See HTML Objects for more information about setting attribute values.

CDN versioning

If you have the CDN enabled then by default images will not have a versioning value added to the image URL. For example, the CDN URL for an image could be like this:

https://cdn.branchcms.com/wBxef4NRL1A-33/images/logo.svg

You may want to add CDN versioning to the file if you want to ensure that the latest version of the image is used with the CDN. With the CDN settings, you can customize the "version" value. Enabling CDN versioning on the image will add that version value before the file extension. For example, if the version value is "3" then the URL for the image could be like this:

https://cdn.branchcms.com/wBxef4NRL1A-33/images/logo.3.svg

There are a few ways to add the CDN versioning to the image.

Using the file_url filter

If you use the file_url filter then the CDN version is automatically added. This applies to images or other file URLs.

{% set image.src = image.src|file_url %}

Use the cdnVersion attribute

The cdnVersion attribute is a boolean value. You can set it to true, false, yes, or no to enable it or disable it.

{# Enable CDN versioning for the individual image #}
{% set image.cdnVersion = true %}
{% set image.cdnVersion = 'true' %}
{% set image.cdnVersion = 'yes' %}

{# Disable CDN versioning for the individual image #}
{% set image.cdnVersion = false %}
{% set image.cdnVersion = 'false' %}
{% set image.cdnVersion = 'no' %}

Use the useCdnVersion function

Instead of setting the cdnVersion attribute directly, you could use the useCdnVersion method to do the same thing.

Enable CDN versioning on the individual image using true, "yes", or no value.

Disable CDN versioning on the individual image using false or "no".

{# Enable CDN versioning for the individual image #}
{% do image.useCdnVersion() %}
{% do image.useCdnVersion(true) %}
{% do image.useCdnVersion('true') %}
{% do image.useCdnVersion('yes') %}

{# Disable CDN versioning for the individual image #}
{% do image.useCdnVersion(false) %}
{% do image.useCdnVersion('false') %}
{% do image.useCdnVersion('no') %}

After you set the CDN versioning then you would typically output the image.

{% set image.cdnVersion = true %}
{{ image.tag }}

Lazy loading images

For performance reasons, it is recommended to lazy load images that aren't guaranteed to be in the initial viewport. Because this is an important attribute we provide a few ways to set it.

Set the "loading" attribute manually

This is probably the most straightforward method. Simply set the "loading" attribute to equal "lazy".

{% set image.loading = 'lazy' %}
or
{% do image.set('loading', 'lazy') %}

Set the "lazy" attribute to true

A slightly shorter option is to set the "lazy" attribute to true or "yes".

{# These are all equivalent #}
{% set image.lazy = true %}
{% set image.lazy = 'true' %}
{% set image.lazy = 'yes' %}
or
{% do image.set('lazy', true) %}
{% do image.set('lazy', 'true') %}
{% do image.set('lazy', 'yes') %}

You can also remove the loading="lazy" attribute in a similar way.

There are only two values for the image loading attribute:

eager (the default value if the "loading" attribute doesn't exist)
lazy

Since there are only two valid values for the loading attribute, if you set it to false then we remove it.

{# These are all equivalent #}
{% set image.lazy = false %}
{% set image.lazy = 'false' %}
{% set image.lazy = 'no' %}
or
{% do image.set('lazy', false) %}
{% do image.set('lazy', 'false') %}
{% do image.set('lazy', 'no') %}

Use the image lazy() method

This is perhaps the most concise option.

{% do image.lazy() %}

You can pass true or false values if you want to either set or remove the loading="lazy" attribute. However, the "true" values aren't required since if no value is passed then lazy() defaults to true.

{# These are all equivalent #}
{% do image.lazy() %}
{% do image.lazy(true) %}
{% do image.lazy('true') %}
{% do image.lazy('yes') %}

{# These are all equivalent to remove the loading="lazy" attribute #}
{% do image.lazy(false) %}
{% do image.lazy('false') %}
{% do image.lazy('no') %}

After you enable or disable the loading="lazy" attribute then you would typically output the image.

{% do image.lazy() %}
{{ image.tag }}

Preloading images and setting fetch priority

In some cases, you may need to prioritize loading an image over other assets on a page. For example, if you have a banner image that shows across the top of a page, you may want that to load over other assets. Or, if you have an image slider at the top of a page, you may want the image in the first slide to load first.

There are two methods to give hints to the browser to prioritize loading assets.

Preloading with a <link> tag in the header.
Setting the fetchpriority attribute on an image.

The fetchpriority attribute is not supported in all browsers, but it may be more effective than preloading.

Preloading is a good backup to fetchpriority for browsers that don't support it.

Preloading images

To preload an image you need to add a <link> tag in the <head> section of the page like this:

<link rel="preload" as="image" href="important.png">

There are two ways that you can do that.

You can manually build the <link> tag.
You can use the preload() method on the image object.

Manually build the link tag

When you are outputting the image tag you can do something like this:

{% head %}
    <link rel="preload" as="image" href="{{ image.src }}">
{% endhead %}

This method works fine, but it can be cumbersome. It also isn't easy to use if you are setting srcset or picture sources on the image tag.

The recommended method is to use the preload() method on the image object.

Use the preload() method on the image object

When the preload() method is called on the image object, it will output the <link> tag when the image tag is output. It will also do the following:

If one or more <picture> tag sources were added to the image object, then each of the picture sources will be preloaded with their media value. By using the media value, the browser can determine which image to preload.
If one or more srcset sources were added to the image object, then "imagesrcset" and "imagesizes" attributes will be added to the <link> tag when preloading the image. See Preloading responsive images for more information.

The preload() method has some options with some good defaults.

media: (string) The value to use for the "media" attribute on the <link> tag. This is typically used if you set one or more picture tag sources for the image.
output: (boolean) Whether to output the <link> tag immediately. By default, the <link> tag is added to the <head> when the image tag is output. If you are manually building the image tag, or not outputting the image tag, then you can set output to true. By default output is false.
priority: (string) The fetchpriority attribute value to add to the <link> tag. This helps to further prioritize preloading the image. By default, the value is "high". Allowed values are "high", "low", and "auto". Only "high" will be output on the <link> tag.

Here are some examples of how to use this.

{# Simplest method #}
{% do image.preload() %}

{# Set options #}
{% do image.preload({media: '(max-width: 500px)', output: true, priority: 'low'}) %}

Setting the fetch priority on the image

The fetchpriority attribute is not supported in all browsers, but it may be more effective than preloading. Here are some resources on setting the fetch priority.

Boost Resource Loading With fetchpriority, A New Priority Hint (Smashing Magazine)
Optimizing resource loading with the Fetch Priority API (web.dev)
Tip - Use fetchpriority=high to load your LCP hero image sooner (Andi Osmani)
Priority Hints: Influence How Browsers Fetch Resources (Calibre)

There are a two ways to set the fetchpriority attribute on images.

Manually add it.
Use the fetchPriority() method on the image object.

Manually adding the fetchpriority attribute

You would set the attribute just like you do with any other attribute on the image object.

{% set image.fetchpriority = "high" %}

Using the fetchPriority() method on the image object

If you use the fetchPriority() method on the image object, then by default, it sets the fetchpriority attribute to "high".

You can, however, set a specific priority value. The following values are allowed:

high
low
auto

{# Default method to set fetchpriority to "high" #}
{% do image.fetchPriority() %}

{# Alternate method to set fetchpriority to "high" #}
{% do image.fetchPriority('high') %}

{# Set fetchpriority to "low" #}
{% do image.fetchPriority('low') %}

{# Set fetchpriority to "auto" #}
{% do image.fetchPriority('auto') %}

Enable preload and fetch priority at once

While you can enable preloading an image and set the fetch priority separately, you can also do it in one method call on the image object.

The prioritize() method will set the image to preload and have a fetch priority of high.

It optionally takes an options object that is the same as the options to the preload() method, as seen above.

media: (string) The value to use for the "media" attribute on the <link> preload tag. This is typically used if you set one or more picture tag sources for the image.
output: (boolean) Whether to output the <link> tag immediately. By default, the <link> tag is added to the <head> when the image tag is output. If you are manually building the image tag, or not outputting the image tag, then you can set output to true. By default output is false.
priority: (string) The fetchpriority attribute value to add to the <link> tag. This helps to further prioritize preloading the image. By default, the value is "high". Allowed values are "high", "low", and "auto". Only "high" will be output on the <link> tag. This will also set the value for the fetchpriority attribute on the image tag.

{# Set the image to preload and have a high fetch priority #}
{% do image.prioritize() %}

{# Set preload options and the fetchpriority value #}
{% do image.prioritize({media: '(max-width: 500px)', output: true, priority: 'low'}) %}

Picture tag

You can output an image tag as a <picture> tag by adding one or more source values with the addSource() method.

The addSource method has the following signature

addSource()
addSource(media)
addSource(media, modifyOptions)

The media parameter sets the media attribute on the picture tag and can be a string with any valid media value. You can also set the media attribute value by using the media() method on the returned source object.

The modifyOptions parameter lets you set any image pipeline modification options. You can also use any of the image pipeline modification methods on the returned source object.

The source URL will be the original image source URL. Typically you modify the image size and/or crop it when adding a picture source.

You can add as many picture tag sources as you want.

Examples

Add source values and crop the output image. The following are equivalent

{% do image.addSource('(max-width: 500px)', {w: 500, h: 200, c: true}) %}
{% do image.addSource().media('(max-width: 500px)').crop(500, 200) %}
{% do image.addSource('(max-width: 500px)').crop(500, 200) %}

Output the image after adding the sources:

If the original image is at images/my-image.jpg then the result from this will be something like this.

Preload the picture source image

You can preload the picture source image at a specific media query value. Use the preloadMedia() method on the source object to do this.

The preloadMedia method has the following signature:

preloadMedia(media)
preloadMedia(minWidth, maxWidth)
preloadMedia(minWidth, maxWidth, resolution)

The media value is the full media query. This gives you the most control.

You can also use the short form by setting a minimum and maximum width with the minWidth and maxWidth parameters. They should be numbers representing a pixel value ("px" will be appended to the value).

If you use the minWidth and maxWidth parameters you can also set a screen pixel density resolution to include in the media query with the resolution parameter.

Examples

{% do image.addSource('(max-width: 500px)').crop(500, 200).preloadMedia('(max-width: 500px)') %}
{{ image.tag() }}

This will add a <link> tag to the <head> section of the page. An example output would be like this:

Set the min/max values with the media parameter.

{% do image.addSource('(max-width: 500px)').crop(500, 200).preloadMedia('(min-width: 500px) and (max-width: 800px)') %}

Or, do the same thing with the minWidth and maxWidth parameters.

{% do image.addSource('(max-width: 500px)').crop(500, 200).preloadMedia(500, 800) %}

The above two examples will output something like this:

You can chain multiple preloadMedia() calls. Subsequent calls will be appended as an OR media query.

{% do image.addSource().media('(max-width: 800px)').preloadMedia(500, 800, 2).preloadMedia(400, 800, 1) %}

If you set multiple picture source values and you need to preload them, then you must set a min/max media query value for the image sources that are in between the smallest and largest. See Using rel=preload for responsive images for more information.

"The main difference between this and the media attributes within the image is that you need to specify both min and max widths for those in-between images. Unlike the <picture> element the browser isn’t going to load only a single image based on what best fits the current screen size. In the case of preload, the browser will load anything that meets the criteria set within the media attribute, even if that means loading images that won’t be output to the page."

Add srcset values to the image tag

Instead of using a picture tag you can add srcset attribute values to the image with the addSrcSet() method.

The addSrcSet method signature is:

addSrcSet()
addSrcSet(width)
addSrcSet(width, modifyOptions)

If you don't pass any parameters then you can use the width() method and the image pipeline modification methods to modify the image.

The width value is the width to use for the srcset value. It should be a string with the correct width unit. For example, "500w" instead of "500".

The modifyOptions parameter lets you set any image pipeline modification options. You can also use any of the image pipeline modification methods on the returned srcSet object.

The following are equivalent

{% do image.addSrcSet('500w', {w: 500, h: 200, c: true}) %}
{% do image.addSrcSet().width('500w').crop(500, 200) %}
{% do image.addSrcSet('500w').crop(500, 200) %}