Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

@regru/loading-attribute-polyfill

mfranzke3MIT1.2.0

Fast and lightweight dependency-free vanilla JavaScript polyfill for native lazy loading / the awesome loading='lazy'-attribute.

lazy loading, native lazy loading, img, image, iframe, polyfill, web development, javascript, html

readme

loading="lazy" attribute polyfill

MIT license loading-attribute-polyfill on Npmjs Total downloads ~ Npmjs jsDelivr CDN downloads Codacy Badge dependencies Status code style: prettier XO code style Conventional Commits Greenkeeper badge

Fast and lightweight vanilla JavaScript polyfill for native lazy loading, meaning the behaviour to load elements right before they enter the viewport. Provides graceful degradation, and is - not just thatfor - SEO friendly. Handles images with srcset and within picture, as well as iframe elements. loading="lazy" will be a huge improvement for todays web performance challenges, so use and polyfill it today!

  • Released under the MIT license
  • Made in Germany

Features

  • Web standards: Supports the standard loading="lazy" attribute on image and iframe elements
  • Performance: It's based on highly efficient, best practice code.
  • SEO & crawlers: The image and iframe contents aren't being hidden from crawlers that aren't capable of scrolling.

Core concepts

The polyfill was designed with the following concepts kept in mind:

  • dependency-free
  • Using JavaScript with graceful degradation

Installation

Just integrate the JavaScript file into your code - et voilà.

You may optionally load via NPM or Bower:

$ npm install loading-attribute-polyfill
$ bower install loading-attribute-polyfill

You could even load the polyfill asynchronously: https://output.jsbin.com/codelib/1

Afterwards you'll need to wrap all of your <img> and <iframe> HTML tags that you'd like to lazy load (and thatfor added a loading="lazy" attribute as well) by an <noscript> HTML tag:

Simple image

<noscript class="loading-lazy">
    <img
        src="simpleimage.jpg"
        loading="lazy"
        alt=".."
        width="250"
        height="150"
    />
</noscript>

Image wrapped in a picture tag

<picture>
    <noscript class="loading-lazy">
        <source
            media="(min-width: 40em)"
            srcset="
                simpleimage.huge.jpg 1x,
                simpleimage.huge.2x.jpg 2x
            "
        />
        <source
            srcset="
                simpleimage.jpg 1x,
                simpleimage.2x.jpg 2x
            "
        />
        <img
            src="simpleimage.jpg"
            loading="lazy"
            alt=".."
            width="250"
            height="150"
        />
    </noscript>
</picture>

Image with srcset

<noscript class="loading-lazy">
    <img
        src="simpleimage.jpg"
        srcset="
            simpleimage.1024.jpg 1024w,
            simpleimage.640.jpg   640w,
            simpleimage.320.jpg   320w
        "
        sizes="(min-width: 36em) 33.3vw, 100vw"
        alt="A rad wolf"
        loading="lazy"
    />
</noscript>

Iframe

<noscript class="loading-lazy">
    <iframe
        src="https://player.vimeo.com/video/87110435"
        width="320"
        height="180"
        loading="lazy"
    ></iframe>
</noscript>

Optional additional dependencies

In case you'd like to support older versions of Microsoft EDGE, Microsoft Internet Explorer 11 or Apple Safari up to 12.0, you could (conditionally) load an IntersectionObserver polyfill:

https://www.npmjs.com/package/intersection-observer

Nevertheless this polyfill would still work in those browsers without that other polyfill included, but this small amount of users wouldn't totally benefit from the lazy loading functionality - we've at least got you partly covered by using the Microsoft proprietary lazyloading resource hints.

API

Nothing really, just plug it in, it will should work out of the box.

Demo

See the polyfill in action either by downloading / forking this repo and have a look at demo/index.html, or at the hosted demo: https://mfranzke.github.io/loading-attribute-polyfill/demo/

Further implementations - Kudos for that

Wordpress

Nico23 has developed a Wordpress plugin: https://wordpress.org/plugins/native-lazyload-polyfill/ (which is much better than the one by Google !)

PHP Twig Extension

@tim-thaler has developed a PHP Twig Extension: https://github.com/tim-thaler/twig-loading-lazy

Craft Twig Loading Lazy plugin

@tim-thaler has even also developed a Craft Twig Loading Lazy plugin: https://github.com/tim-thaler/craft-twig-loading-lazy

Credits

Credits for the initial kickstarter / script to @Sora2455 for better expressing my ideas & concepts and support by @nextgenthemes, @diogoterremoto, @dracos and @Flimm. Thank you very much for that, highly appreciated !

Tested with

  • Mac

    • Mac OSX 10.14, Mozilla Firefox 68.0.1 (manually, localhost)
    • Mac OSX 10.14, Safari 12 (via CrossBrowserTesting)
    • Mac OSX 10.13, Safari 11 (via CrossBrowserTesting)
  • iOS

    • iPad 6th Generation Simulator, Mobile Safari 12.0 (via CrossBrowserTesting)
  • Windows

    • Windows 10, Google Chrome / versions latest & latest-1 (via CrossBrowserTesting)
    • Windows 10, Microsoft EDGE / versions 17, 18 (via CrossBrowserTesting)
    • Windows 10, Microsoft Internet Explorer / version 11 (via CrossBrowserTesting)

Big Thanks

Cross-browser testing platform provided by CrossBrowserTesting

CrossBrowserTesting Join the chat at https://gitter.im/loading-attribute-polyfill/community

things to keep in mind

  • The demo HTML code is meant to be simple
  • This polyfill doesn't (so far) provide any functionality for the loading="eager" value, as this was released even already, but still seems to be in the measure, learn and improvements phase.

More information on the standard

Outro

If you're trying out and using my work, feel free to contact me and give me any feedback. I'm curious about how it's gonna be used.

And if you do like this polyfill, please consider even also having a look at the other polyfill we've developed: https://github.com/mfranzke/datalist-polyfill/

changelog

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog and this project adheres to Semantic Versioning. And the commit messages from Conventional Commits are being used.

[Unreleased]

  • Ongoing: Further documentation

[1.2.0] - 2019-10-15

Added

  • Crawler/"SEO" capabilities
  • Testing: Further browsers and activated the video-recording
  • Lots of further information and documentation
  • Codacy, dependency and Greenkeeper (#18) integrations and badges, yeah !
  • Comment within the demo page clarifying the images content #8
  • Links to further implementations / plugins & extensions

Changed

  • Made changes regarding to xo/prettier tools and codacys (#12) remarks
  • Some even smaller base64 image as an image replacement
  • Loading the sample images locally
  • Update xo to version 0.25
  • Updated webdriver.io's packages to version 5.13.2
  • Code simplifications

Fixed

  • Outdated JSBin link
  • Markdown regarding some readers/interpreters malfunctions

[1.1.0] - 2019-08-15

Changed

  • Added IE, EDGE < version 16 and Safari < version 12 support

[1.0.1] - 2019-08-10

Changed

  • Corrected both the demo-page as well as the documentation on the aspect of wrapping the <source> HTML tags as well

[1.0.0] - 2019-08-10

Added

  • Comment regarding asynchronous loading
  • Webdriver.io testing

Changed

  • BREAKING CHANGE: You#ll need to also wrap the <source> HTML tags within the <picture> tags with <noscript>

Fix

  • Documents markup regarding codacy suggestions
  • Corrected sample image measurements
  • The images didn't load lazily in Safari, but directly, as reported with #GH-3
  • Displaying the images on smaller viewports on the sample page

[0.2.0] - 2019-05-22

Added

  • Changelog
  • Codacy integration and badge
  • Code examples
  • Optional additional dependencies section within the README
  • Optional polyfill for the demo page
  • "Conventional Commits" support as well as their badge - yeah !

Changed

  • Docs formatting
  • Some docs content enhancements
  • Internal namings within the JS file

[0.1.2] - 2019-05-04

Added

  • Documentation

[0.1.1] - 2019-05-01

Added

  • CHANGELOG.md file

[0.1.0] - 2019-05-01

Added

  • Initial files
  • npm and bower support
  • code formatting and linting