Lazy Loading

Lazy Loading

Lazy loading defers image downloads until they are about to scroll into view, cutting initial page weight and speeding up first paint. Canvas uses a lightweight LazyLoad instance that watches every .lazy element and swaps data-src into src as it approaches the viewport.

Core Markup

Give the image the lazy class, a transparent inline SVG placeholder in src, and the real image URL in data-src. Always include width and height to reserve layout space and avoid content shift.

<img class="lazy"
     src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 4 3'%3E%3C/svg%3E"
     width="800" height="600"
     data-src="images/portfolio/4/1.jpg"
     alt="Gallery Thumb 1">

The viewBox ratio in the placeholder SVG should match your image aspect ratio (for example 0 0 4 3 for 4:3, 0 0 1 1 for square) so the reserved box is correctly proportioned.

State Classes

The plugin toggles classes through the load lifecycle, which you can hook into with CSS:

• lazy-loading: applied while the image is downloading.
• lazy-loaded: applied once the image has finished loading. The selector only targets .lazy:not(.lazy-loaded), so loaded images are never reprocessed.
• lazy-error: applied if the image fails to load.

In a Gallery

Lazy images pair well with the lightbox gallery. Wrap each in an anchor pointing at the full-size image:

<div class="grid-container row row-cols-4">
    <a class="grid-item col" href="images/portfolio/full/1.jpg" data-lightbox="gallery-item">
        <img class="lazy"
             src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 4 3'%3E%3C/svg%3E"
             width="800" height="600"
             data-src="images/portfolio/4/1.jpg" alt="Gallery Thumb 1">
    </a>
</div>

Lazy Containers

If a lazy image is wrapped in a container marked data-lazy-container="true", Canvas re-runs its shortcode modules inside that container once the image loads. This keeps carousels and grids correctly sized after lazy images arrive.

Tips

• Do not lazy-load above-the-fold hero images. Those should load eagerly so the largest contentful paint is fast.
• Match the placeholder SVG viewBox to the real aspect ratio to prevent layout shift.
• The lazy-loaded class means an image is done, so any hover or transition CSS can safely target .lazy-loaded.