Lazy Loading Assets for Performance

Last updated:

Lazy loading assets is the act of deferring the loading of the assets until the time that they are actually needed. On the web, this often means downloading the designated content only once the user has gotten sufficiently close to where in the HTML document the asset displays.

Lazy loading images

At this time, lazy loading options are only available for the image field in custom modules. We are currently looking into rolling this out into our default modules and will update our docs and changelogs accordingly when this is available.

When building custom modules, you have the option to enable browser built-in lazy loading on image fields. When enabled, you can choose whether to show or hide controls to the content editor enabling them to change the loading behavior in the page editor.

Browser Compatibility

Lazy loading of images via the loading attribute is supported by most of the popular Chromium-powered browsers (Chrome, Edge, Opera) and Firefox. To learn more about what browsers are supported you can visit caniuse.com. Browsers that do not support the loading attribute will simply ignore it without side-effects.

Add lazy loading to Image fields using the CLI

To enable lazy loading of images while building with the CMS CLI, add the show_loading and loading keys to your image field in your fields.json file. Learn more about Module and Theme Field Types.

JSON
// fields.json file 
{
  "id" : "357bacfa-2bb8-e996-4589-f55e10d4f1d4",
  "name" : "image_field",
  "label" : "Image",
  "required" : false,
  "locked" : false,
  "responsive" : true,
  "resizable" : true,
  "show_loading" : false,
  "type" : "image",
  "default" : {
    "size_type" : "auto",
    "src" : "",
    "alt" : null,
    "loading" : "disabled"
  }
}
Use this table to describe parameters / fields
Parameter Type Description Default
show_loading
Boolean

Controls showing/hiding lazy load controls to the content editor.

False
loading
String

Determines whether to use lazy loading. Options include: "disabled" or "lazy"

"disabled"

You can then reference these variables in your module.html file using the following syntax:

HubL
{% set loadingAttr = module.image_field.loading != 'disabled' ? 'loading="{{ module.image_field.loading }}"' : '' %}
<img src="{{ module.image_field.src }}" alt="{{ module.image_field.alt }}" {{ loadingAttr }}>

Add lazy loading to image fields using the Design Manager

To enable lazy loading, add an image field to your custom module, then navigate to the Content options section in the Inspector pane. In this section, you will see both the Image loading and Available loading options select menus.

Lazy loading controls in the Design Manager

Image loading

The Image loading option will set the value of the loading attribute in the browser. Options for this include "Default" (default option) which is the default browser loading behavior for the asset. When enabling lazy loading, the image will load once the image reaches a certain distance from the viewport as defined in the distance-from-viewport threshold.

Available loading options

The Available loading options will determine if content editors will be able to see and set the Image loading option while inside of the page, global, and theme content editor panes. Options for this include “Do Not Show Controls” (default option) or “Show all controls”.  Below is a sample of what the page editor would look like with “Show all controls” selected:

Lazy loading controls on the page editor