This is particularly valuable for mobile users on slow connections or limited data plans. If an image is only meaningful on larger screens, why waste their bandwidth loading it at all?

# The performance benefit

Unlike picture or srcset, which always load some image variant, lazy-img can completely skip loading images on screens or containers below your specified threshold. Set min-inline-size="768px" and mobile users will never download that image at all—saving data and speeding up page loads.

Once an image is loaded, however, it remains loaded even if the viewport or container is resized below the threshold. This is intentional—the component prevents unnecessary downloads but doesn’t unload images already in memory. You can control visibility with CSS if needed using the loaded and qualifies attributes (which we’ll get to shortly).

# Basic usage

The lazy-img works pretty much identically to a regular img element, with all the attributes you know and love:

<lazy-imgsrc=“image.jpg”alt=“A beautiful image”></lazy-img>

But that’s not very interesting. The real power comes from conditional loading.

# Container queries (default)

Load an image only when its container reaches a minimum width:

<lazy-imgsrc=“large-image.jpg”alt=“Large image”min-inline-size=“500px”></lazy-img>

The image loads when the lazy-img element’s container reaches 500px wide. This is the default query mode—it uses ResizeObserver to watch the container size.

# Media queries

You can lazy load images based on viewport width instead by switching to media query mode:

<lazy-imgsrc=“desktop-image.jpg”alt=“Desktop image”min-inline-size=“768px”query=“media”></lazy-img>

With this configuration, the image loads when the browser window is at least 768px wide.

# View mode (scroll-based loading)

Load images when they scroll into view using IntersectionObserver by switching to the “view” query type:

<lazy-imgsrc=“image.jpg”alt=“Loads when scrolled into view”query=“view”></lazy-img>

The default behavior (view-range-start="entry 0%") loads as soon as any part of the image enters the viewport.

Control when images load with the view-range-start attribute:

Load when 50% visible:

<lazy-imgsrc=“image.jpg”alt=“Loads when half visible”query=“view”view-range-start=“entry 50%”></lazy-img>

Preload before entering viewport:

<lazy-imgsrc=“image.jpg”alt=“Preloads 200px before visible”query=“view”view-range-start=“entry -200px”></lazy-img>

This creates a smooth user experience—images are already loaded by the time users scroll to them.

# Responsive images

As with regular images, you can use srcset and sizes for responsive images:

<lazy-imgsrc=“image-800.jpg”srcset=“image-400.jpg 400w,image-800.jpg 800w,image-1200.jpg 1200w”sizes=“(max-width: 600px) 400px,(max-width: 1000px) 800px,1200px”alt=“Responsive image”min-inline-size=“400px”></lazy-img>

The component waits until the conditions are met before loading a real image and the browser takes over from there.

# Named breakpoints

You can also define named breakpoints using CSS custom properties:

:root{–lazy-img-mq: small;}@media(min-width: 768px){:root{–lazy-img-mq: medium;}}@media(min-width: 1024px){:root{–lazy-img-mq: large;}}

Then reference them in your markup:

<lazy-imgsrc=“image.jpg”alt=“Image with named breakpoints”named-breakpoints=“medium, large”query=“media”></lazy-img>

The image loads when –lazy-img-mq matches “medium” or “large”.

# Preventing layout shift

As with regular images, don’t forget to use width and height attributes to prevent Cumulative Layout Shift (CLS):

<lazy-imgsrc=“image.jpg”alt=“A beautiful image”width=“800”height=“600”min-inline-size=“768px”></lazy-img>

The browser reserves the correct space while the image loads, preventing content from jumping around.

# State attributes for styling

The component provides loaded and qualifies attributes you can use in CSS:

/* Hide images that loaded but no longer meet conditions /lazy-img[loaded]:not([qualifies]){display: none;}/ Show a placeholder for images that qualify but haven’t loaded */lazy-img[qualifies]:not([loaded])::before{content:“Loading…”;display: block;padding: 2em;background: #f0f0f0;text-align: center;}

# Events

If you crave control, you can add your own functionality by listening for when images load:

const lazyImg = document.querySelector(“lazy-img”);lazyImg.addEventListener(“lazy-img:loaded”,(event)=>{console.log(“Image loaded:”, event.detail.src);});

# Performance

The component is highly optimized:

• Throttled resize: Resize events are throttled to prevent excessive checks
• Shared ResizeObserver: Multiple images observing the same container share a single ResizeObserver
• Shared window resize listener: Media query mode shares a single window resize listener
• Shared IntersectionObserver: View mode with the same view-range-start shares an IntersectionObserver
• Clean disconnection: Properly cleans up observers when elements are removed

Even with hundreds of lazy-img elements on a page, performance remains excellent.

# Progressive enhancement

If JavaScript fails to load, images simply don’t appear (unless using immediate loading mode). This might sound problematic, but for non-critical images—decorative graphics, supplementary screenshots, marketing imagery—it’s often exactly what you want. Your content remains accessible; you just lose the enhancements.

For critical images that are part of your content, use standard img tags. Use lazy-img for conditional enhancements.

# Demo

Explore the demo to see container queries, media queries, scroll-based loading, and more in action:

# Grab it

Check out the project on GitHub. Install via npm:

npminstall @aarongustafson/lazy-img

Import and use:

import“@aarongustafson/lazy-img”;

Based on my original Easy Lazy Images concept, reimagined as a modern custom element.

JAIL’s a cool little script that takes care of lazy loading images for you in order to speed up initial page rendering. To use it, you implement the following markup pattern:

This is pretty ingenious actually. Without JS, the actual image is served up, but with JavaScript, the blank image is displayed until JAIL lazy loads the real image path stored in the data-src attribute. You initialize JAIL like this:

Simple, right? Well, yes and no.

On a site that isn’t updated frequently and where a skilled front-end coder is involved, this is cake. That, however, is seldom the reality. Heck, even on this blog, remembering to use that pattern while authoring content in the backend is not terribly likely. I needed a way to make it easier. So I automated JAIL as an ExpressionEngine plug-in.

With this plug-in I can automatically enable (or remove) JAIL at the template level with a simple tag pair: exp:easy_jail:prep

The plugin will hunt for any image elements inside the tag pair and convert them to use the JAIL markup pattern. By default, it uses a base-64 encoded representation of a blank GIF (a.k.a. a Data URI) to reduce the number of requests, but you can override that with the path to your own image (or a different Data URI) using the blank_img property. You can also customize the class used for the blank image using the class_name property.

Then it’s just a matter of including the JAIL JavaScript code and executing it. You can, of course, include Sebastiano’s script and your JAIL config in your own JavaScript build, but the plug-in also includes a convenience function to drop it in for you. Simply add the exp:easy_jail:js tag before the close of the body element (after jQuery of course):

As with the exp:easy_jail:prep tag, you can customize the JavaScript output using the class_name property to tell JAIL what to lazy load. You can also customize the JAIL configuraiton using the config property. Just pass in a valid JSON object describing the configuration you want. JAIL is pretty darn configurable. There are a ton of options available, but the most intriguing to me currently is offset. We’re using it here on the blog to load images when you scroll to within 300px of the top of the image. Here’s how you’d do that using the plug-in:

And there you have it. Simple, lazy loaded images without having to train content editors to author the relatively complex markup pattern. If you want to have a play, feel free to grab the code from Github or you can fork it and help us to make it even more useful.

In a few recent projects, we’ve been offering high resolution graphics—mainly logos, icons and the like only for now as we’re not looking to kill anyone’s mobile bandwidth allotment—to devices with a pixel density of two or more (@media screen and (min-pixel-density:2)). Interestingly, the same technique I came up with years ago is perfectly suited for this purpose in addition to letting you set a small, low resolution baseline image (mobile-first, ya know), replacing it with larger and/or higher resolution images as real estate or device supports it.

For those not keen to read my original article, here’s the jist (or gist—harharhar): take your favorite image-replacement technique and apply it to an img element. As a means of demonstrating the concept, here’s two images:

With those in place, you simply apply your preferred image-replacement technique to the img elements. I’m partial to Leahy/Langridge:

All that’s required to re-purpose this technique for high resolution images is to add in the background-size property (set to the dimensions of the original low density image, of course):

I think it’s a pretty useful technique overall. Of course it’s only really useful for presentational images; it doesn’t really make sense for content images. And, of course, there’s still the question of whether it’s advisable to load a high-resolution image for someone who may be on a metered connection. If you are concerned about that sort of thing, take heart that the W3C is working on the issue. In the meantime, however, you may want to consider Foresight.js.

I am well-aware of the issues regarding IE’s handling of alpha transparency in 24-bit PNGs, but had not heard of any color-related issues with 8-bit PNGs in IE6. I did a test in IE7B2 to see if the error was there too and it was.

I did some searching on Google and couldn’t seem to find any documentation on this bug, but it’s certainly something I’d recommend they fix for the final release of IE7. For now, however, the only solutions appear to be adding color-correction to your CSS for IE (if you are dead-set on using an 8-bit PNG) or using a GIF.