Lazy loading assets allows you to defer the loading of the assets until the time when 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. This technique is one of many suggested for optimizing page performance.
Lazy loading options are available for the image and logo fields in custom modules for use in HubL tags and also available in the default image module.
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.
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.
To enable lazy loading of images while building with the CMS CLI, add the show_loading and loading keys to the image or logo field in the module's fields.json file.
// 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" }}| 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:
xxxxxxxxxx{% set loadingAttr = module.image_field.loading != 'disabled' ? 'loading="{{ module.image_field.loading }}"' : '' %}<img src="{{ module.image_field.src }}" alt="{{ module.image_field.alt }}" {{ loadingAttr }}>To enable lazy loading, add an image or logo field to your custom module, then navigate to the Content options section in the Inspector pane. Then use the Image loading and Available loading options dropdown menus to configure the image loading behavior.
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.
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) or Show all controls. Below is a sample of what the page editor would look like with Show all controls selected:
You can then reference these variables in the module.html file using the following syntax:
xxxxxxxxxx{% set loadingAttr = module.image_field.loading != 'disabled' ? 'loading="{{ module.image_field.loading }}"' : '' %}<img src="{{ module.image_field.src }}" alt="{{ module.image_field.alt }}" {{ loadingAttr }}>