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.

Great summary here:

[M]y passion for accessibility stems from experiencing accessibility barriers personally, observing their impact on others, and holding the conviction that technology should tear down divides - not erect new ones. I want to fulfill, and help you fulfill, the web’s promise of equal access and opportunity for everyone, regardless of circumstances. Digital accessibility should not be an accommodation but a fundamental right and prerequisite for technology to truly better humanity.

Lots of juicy stats to share in your team discussions!

Using progressive enhancement means your users will be able to do what they need to do if any part of the stack fails. Building your service using progressive enhancement will:

• make your service more resilient
• mean your service’s most basic functionality will work and meet the core needs of the user
• improve accessibility by encouraging best practices like writing semantic markup
• help users with device or connectivity limitations to use your service

🥰

In this piece for WebPageTest, Scott Jehl uses a new “experiments” feature to demonstrate how serving HTML would make a ton of popular websites much, much faster. Some of these companies learned this lesson previously (and even wrote about it) only to have thrown their own advice out the window, which is disappointing.

Serving HTML will always result in faster page loads. There is no way around that. Sending your JavaScript framework to the client and having it render the HTML adds a ton of extra steps:

1. Download skeleton markup
2. Download high priority JavaScript file(s) and CSS
3. Load JavaScript program into memory
4. Execute JavaScript
5. Generate actual markup (and replace skeleton)
6. Request assets referenced in markup (e.g., images, videos)
7. Render page
8. Load deferred assets

Compare that to the HTML-first route:

1. Download markup
2. Download high priority JavaScript file(s) and CSS
3. Request assets referenced in markup (e.g., images, videos)
4. Render page
5. Load deferred assets

Sure, on subsequent navigations having JavaScript request only the bits and pieces you need is a performance win, but that first render is a beast. And you can totally load that JavaScript later, after the page is rendered.

In this session, Aaron discusses the many challenges to delivering critical information and services as well as the steps you can take to overcome those challenges. He’ll explore ways to make sure you can meet users on a variety of devices—and not the just the latest and greatest high end ones folks are talking about; how to make it accessible to people with disabilities; and how to load—and load quickly—on limited-bandwidth connections.

Good frameworks should provide a better starting point on the essentials (security, accessibility, performance) or have built-in constraints that make it harder to ship something that violates those.

That doesn’t appear to be happening with performance (nor with accessibility, apparently).

…

What is clear: right now, if you’re using a framework to build your site, you’re making a trade-off in terms of initial performance—even in the best of scenarios.

Some trade-off may be acceptable in the right situations, but it’s important that we make that exchange consciously.

Do yourself a favor and tuck into the numbers here. He presents a substantial amount of very useful information.

This problem is on us. Yes, we need to better prioritize our asset delivery, but most importantly, we need to stop delivering so much JavaScript. We need to audit our script inventory, and scrutinize our 3rd party integrations regularly, as many of these packages are abandoned or meant to be short-lived. … We should do whatever we can to keep our team members aware of their own impact, across all roles.

There was a common assertion that slow networks were a third-world challenge. Remember Facebook’s network challenges? They always talked about new markets in India and Africa. The implication is that this isn’t our problem in, say, Omaha or New York.

Pew Research provided a lot of data back then that showed that this thinking was wrong. Use of cell phones, especially smartphones and tablets, escalated dramatically in the United States. There was a trend towards mobile-only usage. This was in low-income households—about one third of the population. Among 5,400 panelists, 15% did not have a JavaScript-enabled device.

In this session, I discuss some of the potential pitfalls in implementing Service Workers, especially when it comes to managing heavy files like images and video. He’ll provide guidance on current best practices in cache management. And he’ll offer a few simple recipes you can put to use right away to deliver amazing experiences for your users that respect their data usage and disk space.

Note: I no longer use “native” in this context, but it remains in quoted material.

The Web is an undependable place, so this shouldn’t be very surprising.

In this intensely practical session, Aaron will explore the ins and outs of page load performance by showing how he made the web site of the 10K Apart meet its own contest rules, by having a site that was functional and attractive even without JavaScript, and was less than ten kilobytes at initial load. You’ll walk away with a better understanding of the page load process as well as numerous ways you can improve the projects you are working on right now.