Responsive Progressive Image Lazy Loading Component – progressive-image

Preview:

Description:

This is a custom-element that allows you to progressively loading images when the placeholders are clicked/tapped or scrolled into view.

More Features:

• Responsive image delivery via srcset and sizes attributes.
• Automatically enables the Load On Click functionality for slow connections (2g, 3g, etc).
• Apply custom CSS styles to the image when loading and after loaded.

How to use it:

1. Install the progressive-image package.

# NPM
$ npm install progressive-image-element --save

2. Load the necessary JavaScript and CSS files from CDN.

<link rel="stylesheet" href="https://unpkg.com/progressive-image-element@latest/dist/progressive-image-element.css">
<script src="https://unpkg.com/progressive-image-element@latest/dist/index.js"></script>

3. Insert your image into the <progressive-image> custom element.

<progressive-image 
  src="1.jpg" 
  srcset="1.jpg 2x, 1.jpg 1x">
  <img src="placeholder.jpg" width="300" height="200" alt="Must Have Width/Height Attributes" />
</progressive-image>

4. Add the savedata (true/false) attribute to the <progressive-image> custom element to load the image on click/tap instead.

<progressive-image 
  savedata
  src="1.jpg" 
  srcset="1.jpg 2x, 1.jpg 1x">
  <img src="placeholder.jpg" width="300" height="200" alt="Must Have Width/Height Attributes" />
</progressive-image>

5. Apply your own CSS styles to the image according to the loading status.

progressive-image {
  background-color: rgba(0, 0, 0, 0.05);
}
progressive-image.loadable:before,
progressive-image.loading:before {
  content: "";
  cursor: pointer;
  display: block;
  z-index: 1;
  position: absolute;
  top: 0;
  left: 0;
}
progressive-image.loadable:before {
  right: 0;
  bottom: 0;
  background-repeat: no-repeat;
  background-position: 16px 16px;
  background-size: 24px;
  background-image: url('data:image/svg+xml,    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor">      <path d="M0 0h24v24H0z" fill="none"/>      <path d="M12 4.5C7 4.5 2.73 7.61 1 12c1.73 4.39 6 7.5 11 7.5s9.27-3.11 11-7.5c-1.73-4.39-6-7.5-11-7.5zM12 17c-2.76 0-5-2.24-5-5s2.24-5 5-5 5 2.24 5 5-2.24 5-5 5zm0-8c-1.66 0-3 1.34-3 3s1.34 3 3 3 3-1.34 3-3-1.34-3-3-3z"/>    </svg>');
}
progressive-image.loading:before {
  background-color: #000;
  animation: running-progress 2s cubic-bezier(0.4, 0, 0.2, 1) infinite;
  height: 3px;
  width: 100%;
}
progressive-image > img {
  opacity: 0;
  transition: opacity 400ms ease 0ms;
}
progressive-image > img:first-of-type {
  filter: blur(100px);
}
progressive-image > img.loaded {
  opacity: 1;
}
@keyframes running-progress {
  0% {
    margin-left: 0px;
    margin-right: 100%;
  }
  50% {
    margin-left: 25%;
    margin-right: 0%;
  }
  100% {
    margin-left: 100%;
    margin-right: 0;
  }
}

Changelog:

v1.3.0 (03/25/2025)

• feat: introduce ES module support
• feat: allow opt-out of define()