progressive-img v1.0.0

Custom element <progressive-img>

Custom element (written in Polymer) to load img progressively and lazily. It first shows tiny blurred placeholder and loads full-sized image afterwards. It can also defer loading until placeholder is clicked or enters viewport.

Demo

Basic usage

You basically take all your <img> tags, change them to <progressive-img> and add placeholder attribute. It will display a blurred placeholder and load src/srcset after being clicked.

<progressive-img
    src="..."
    srcset="..."
    sizes="..."
    alt="..."
    placeholder="my-placeholder.jpg">
</progressive-img>

Load strategy

<progressive-img
    srcset="..."
    placeholder="..."
    alt="..."
    load-strategy="instant | on-visible">
</progressive-img>

Load strategy controls when image starts loading. There are 3 options:

Clicking the placeholder will always trigger image loading no matter what. You can completely leave out load-strategy if that's all you need.

Intersection margin

<progressive-img
    srcset="..."
    placeholder="..."
    alt="..."
    load-strategy="on-visible"
    intersection-margin="500px">
</progressive-img>

Intersection margin only takes effect if load-strategy="on-visible" is set. Default value is 200px, so image will trigger loading when enters 200px wide area around viewport.

For this effect, progressive-img uses intersectionObserver API. Here you can read more about how it works:

• Google dev docs
• Arnelle Balane's medium blog post
• Mozilla docs

intersection-margin attribute is assigned to rootMargin of intersection observer, so you can use any valid value of rootMargin.

IntersectionObserver Polyfill

If you need to use load-strategy=on-visible in browsers that don't currently support intersection API, you can just include official polyfill: https://github.com/w3c/IntersectionObserver/tree/master/polyfill, it's one liner.

What about browsers with disabled javascript?

Without js, progressive-img can't load. Which is great because you can easily create fallback:

<progressive-img src="..." alt="..." placeholder="..."></progressive-img>
<noscript>
  <img src="" alt="">
</noscript>

Styling

progressive-img uses 4 CSS custom properties to customize the appearance.

You can find examples of this in demo page