Performance Benefit: Unlike
picture or srcset which always load
some image, lazy-img can completely skip
loading images on screens below your threshold. This saves
bandwidth and improves performance for users on smaller devices
or slower connections.
Note on Resize Behavior: Once an image is
loaded, it remains loaded even if the viewport or container is
resized below the threshold. This is intentional for performance
— the component prevents unnecessary downloads, but doesn't
unload images that are already in memory. Use the
loaded and qualifies attributes to
control visibility with CSS if needed.
Basic Example
Simple image that loads immediately (no conditions).
💡 Performance Note: While this pattern
loads the image immediately (like a standard
img), it still provides a benefit:
if JavaScript fails to load or execute, the image won't
load at all. This can be desirable for non-critical, optional images
that enhance but aren't essential to the content (e.g.,
decorative images, supplementary graphics, or marketing
banners).
⚠️ Important: Only use this pattern for
non-critical images that aren't referenced in your content.
Critical images that are part of your content should use
standard img tags to ensure they load even when
JavaScript is unavailable.
Basic Usage
<lazy-img
src="./sample.svg"
alt="Mountain trail at sunrise illustration">
</lazy-img>
Container Query Example (Default)
💡 Key Feature: Images only load when the container reaches the minimum size. If the container never gets that big, the image never loads — saving bandwidth! The default query type is "container".
Try it: Each container below starts smaller than needed. Use its labeled width slider (arrow keys, Home, and End), or drag the resize handle (bottom-right corner), to widen the container and watch the image lazy load when it hits the threshold.
Small Container (min-inline-size: 300px)
👉 Widen this container to 300px to see the image load. It starts at 200px (too small), so the image won't load until you resize it.
<lazy-img
src="./sample.svg"
alt="Mountain trail at sunrise illustration"
min-inline-size="300">
</lazy-img>
Medium Container (min-inline-size: 500px)
👉 Widen this container to 500px to trigger the image load.
<lazy-img
src="./sample.svg"
alt="Mountain trail at sunrise illustration"
min-inline-size="500">
</lazy-img>
Media Query Example
Image loads based on viewport width. Uses
query="media" to check window width instead of
container width. This is perfect for saving bandwidth on
mobile devices — if the viewport is below 768px, this image
never loads.
Try it: Resize your browser window to see the effect. The image loads when the viewport reaches 768px wide.
Viewport Width Check (min-inline-size: 768px)
<lazy-img
src="./sample.svg"
alt="Mountain trail at sunrise illustration"
min-inline-size="768"
query="media">
</lazy-img>
Current viewport width: px
View Mode (Scroll-Based Loading)
Image loads when scrolled into view using
IntersectionObserver. Uses query="view" for
scroll-based lazy loading. This is the classic "lazy load as
you scroll" pattern — images only load when they become
visible or are about to become visible.
Try it: Scroll down to see images load as
they enter the viewport. The timing can be controlled with
view-range-start.
Basic View Mode (default: entry 0%)
Loads as soon as any part of the image enters the viewport.
<lazy-img
src="./sample.svg"
alt="Mountain trail at sunrise illustration"
query="view">
</lazy-img>
👇 Scroll down to see the image below load
Image not requested yet (requires JavaScript).
Threshold-Based (entry 50%)
Loads when 50% of the image is visible.
<lazy-img
src="./sample.svg"
alt="Mountain trail at sunrise illustration"
query="view"
view-range-start="entry 50%">
</lazy-img>
👇 Scroll until 50% of the image is visible
Image not requested yet (requires JavaScript).
Preload Before Visible (entry -200px)
Starts loading 200px before the image enters the viewport (smooth UX).
<lazy-img
src="./sample.svg"
alt="Mountain trail at sunrise illustration"
query="view"
view-range-start="entry -200px">
</lazy-img>
👇 Image loads 200px before you see it
Image not requested yet (requires JavaScript).
Responsive Images with srcset and sizes
Combine lazy loading with responsive images using srcset and sizes attributes.
srcset with sizes
👉 Widen this container to 400px to load the responsive image. Once loaded, the browser chooses the appropriate size from srcset.
<lazy-img
src="./sample.svg"
srcset="./sample-small.svg 400w,
./sample.svg 800w,
./sample-large.svg 1200w"
sizes="(max-width: 600px) 400px,
(max-width: 1000px) 800px,
1200px"
alt="Mountain trail at sunrise illustration"
min-inline-size="400">
</lazy-img>
Named Breakpoints (CSS Custom Property)
Use the --lazy-img-mq CSS custom property on
:root to define named breakpoints. Set
different values at different media queries, and images will
load when the breakpoint name matches.
Example with Named Breakpoints
This demo sets --lazy-img-mq via CSS media
queries. Try resizing your browser window to see
different breakpoint values.
<style>
:root {
--lazy-img-mq: small;
}
@media (min-width: 768px) {
:root {
--lazy-img-mq: medium;
}
}
@media (min-width: 1024px) {
:root {
--lazy-img-mq: large;
}
}
</style>
<lazy-img
src="./sample.svg"
alt="Mountain trail at sunrise illustration"
named-breakpoints="medium, large"
query="media">
</lazy-img>
Current breakpoint: small
Image loads when breakpoint is "medium" or "large" (viewport ≥ 768px)
Events
The component dispatches a
lazy-img:loaded event when it creates the image
and starts its request. This event does not confirm that the
image downloaded or decoded.
Event Example
👉 Widen this container to 350px to trigger the load event.
<lazy-img
id="event-demo"
src="./sample.svg"
alt="Mountain trail at sunrise illustration"
min-inline-size="350">
</lazy-img>
<script>
document.getElementById('event-demo')
.addEventListener('lazy-img:loaded', (e) => {
console.log('Image loaded:', e.detail.src);
});
</script>
Event status: waiting for a request (requires JavaScript).
State Attributes
The component provides two boolean attributes to track
state:
loaded (has the image request started?) and
qualifies (does it currently meet conditions to
show?). These allow you to control visibility with CSS.
Controlling Visibility
This example hides images that loaded but no longer qualify (e.g., after device rotation or resize).
<style>
/* Hide loaded images that don't qualify */
lazy-img[loaded]:not([qualifies]) {
display: none;
}
</style>
<lazy-img
src="./sample.svg"
alt="Mountain trail at sunrise illustration"
min-inline-size="400">
</lazy-img>
Optional image download failure
Optional images can fail to download even after
loaded is set. This intentionally missing image
keeps an authored description and recovery link available.
<lazy-img src="./missing-image.jpg"
alt="Mountain trail at sunrise"></lazy-img>
<p>If the image is unavailable:
mountain trail at sunrise.
<a href="./sample.svg">Open an alternative image</a>.
</p>
If the image is unavailable: mountain trail at sunrise. Open an alternative image.
Essential image without JavaScript
Use a native img for essential content rather
than relying on custom-element enhancement. This separate
example loads with or without JavaScript; its description
and recovery link remain available if the image fails.
<figure>
<img src="./sample.svg" width="800" height="400"
alt="A mountain trail at sunrise, shown as a simple illustration" />
<figcaption>This essential image works without JavaScript.</figcaption>
</figure>
<p>If the image is unavailable: mountain trail at sunrise.
<a href="./sample.svg">Open an alternative image</a>.
</p>
If the image is unavailable: mountain trail at sunrise. Open an alternative image.
API Reference
For complete documentation of attributes, events, and browser support, see the README.