progressive-img | Vaadin

Custom element - like img, but progressive and lazy.

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.


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.


Load strategy

    load-strategy="instant | on-visible">

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

Load strategy Behavior
instant image will start loading immediately
on-visible image will load if is visible or when enters viewport

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


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.

intersection margin

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

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:, 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>
  <img src="" alt="">


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

CSS property description
--placeholder-filter Filter applied to placeholder image. Defaults to blur(10px) saturate(1.2)
--placeholder-scale Transform scale value. Defaults to 1.1 to prevent blurred placeholder from having white borders
--transition-duration Duration of swapping placeholder and final image. Defaults to .2s
--transition-timing-function Timing function of swapping placeholder and final image. Defaults to ease-in

You can find examples of this in demo page


Link to this version
ImportedReleased 27 May 2018BSD 3-clause "New" or "Revised" License
Framework Support
Polymer 3.0+
Browser Independent
Install with
npm install progressive-img"@1.0.0"
Run the above npm command in your project folder. If you have any issues installing, please contact the author.
Release notes - Version 1.0.0


  • @polymer/polymer#^3.0.0
  • eslint-plugin-import#^2.12.0
  • eslint-plugin-jsx-a11y#^6.0.3
  • eslint-plugin-react#^7.8.2