Skip to main content
Last modified: August 22, 2025
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 images

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.

​
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 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"
  }
}
ParameterTypeDescriptionDefault
show_loadingBooleanControls showing/hiding lazy load controls to the content editor.False
loadingStringDetermines 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: 
{% 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 and logo fields in HubSpot

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.
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) 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
You can then reference these variables in the module.html file using the following syntax: 
{% set loadingAttr = module.image_field.loading != 'disabled' ? 'loading="{{ module.image_field.loading }}"' : '' %}
<img src="{{ module.image_field.src }}" alt="{{ module.image_field.alt }}" {{ loadingAttr }}>