Wondering what’s next for npm?Check out our public roadmap! »

    uncloakjs

    1.1.9 • Public • Published

    Uncloak

    • Uses IntersectionObserver API to reveal elements, lazy load content, and autoplay/pause videos as they scroll into view
    • Supports dynamically added elements
    • 5KB minified (inc. VideoPlayer)

    How it works

    • Add data-uncloak-new to any elements you would like to be picked up by Uncloak
    • Create new instance of Uncloak - this will automatically query all elements with this attribute
    • Each element will be created as an UncloakItem (or UncloakVideoItem), and:
      • Its data-uncloak-new attribute will be removed (so it won't be picked up again)
      • Be added to a a global IntersectionObserver instance (attached to Uncloak), to be revealed when its node is visible in the viewport
      • Will query for any child elements to be lazy loaded (with data-uncloak-src, data-uncloak-srcset, data-uncloak-picture attributes) - in which case, will setup its own IntersectionObserver instance with a margin of 50% around the viewport
      • If it is an UncloakVideoItem, the video will autoplay once within 25% of the viewport (and paused if outside)
    • If you dynamically add anymore elements and want them to be picked up by Uncloak:
      • Make sure they have the data-uncloak-new attribute
      • Run uncloak.findNewItems() after they've been added to the DOM

    TODO: UncloakVideoItem docs

    Settings

    All settings are optional, defaults are listed below:

    new Uncloak({
      items = []; // an array of UncloakItem / UncloakVideoItem that are to be revealed
      
      // Sent to UncloakItem
      itemOptions = {
        delayTypes: {},
        callbacks: {}
      };
    });
    

    TODO: callbacks & delay types

    Example

    HTML:

    <div class="uncloak uncloak--cloaked" data-uncloak-new>
      <img data-uncloak-src="image.jpg">
    </div>
    
    <div class="uncloak uncloak--cloaked" data-uncloak-new>
      <iframe data-uncloak-src="https://www.youtube.com/embed/G9KQfnqukno" frameborder="0"></iframe>
    </div>
    

    JS:

    import Uncloak from 'path/to/uncloak.js';
    
    new Uncloak();
    

    CSS:

    .uncloak {
      transition: opacity 0.2s;
    }
    .uncloak--cloaked {
      opacity: 0;
    }
    

    Example: Iframe with poster image

    HTML:

    <!-- both elements have the data-uncloak-src so will be lazy loaded with Uncloak -->
    <div class="uncloak uncloak--cloaked embed" data-uncloak-new>
      <!-- could add an event listener to play iframe video & hide poster on click --> 
      <button class="embed__poster">
        <img data-uncloak-src="https://placekitten.com/1440/810">
      </button>
      <iframe class="embed__iframe" data-uncloak-src="https://www.youtube.com/embed/G9KQfnqukno" frameborder="0"></iframe>
    </div>
    

    JS:

    import Uncloak from 'path/to/uncloak.js';
    
    new Uncloak();
    

    CSS:

    .uncloak {
      transition: opacity 0.2s;
    }
    .uncloak--cloaked {
      opacity: 0;
    }
    
    .embed {
      position: relative;
    }
    .embed__iframe {
      height: 100%;
      left: 0;
      position: absolute;
      top: 0;
      width: 100%;
    }
    .embed__poster {
      position: relative;
      z-index: 2;
    }
    

    Example: Lazy picture element

    • Mark the picture element with data-uncloak-picture
    • Don't add an <img> inside the picture to prevent loading
    • Add a fallback source (via data-uncloak-ie-src) to be loaded on the <img> in IE (which doesn't support <picture>)
    • Optionally, add some alt text (data-uncloak-alt) or classes (data-uncloak-class) to be added to the <img> when it's created

    HTML:

    <picture data-uncloak-picture data-uncloak-ie-src="src" data-uncloak-alt="Some alt text" data-uncloak-class="img-cls-1 img-cls-2">
      <source srcset="https://placekitten.com/1440/810" media="(min-width: 1024px)">
      <source srcset="https://placekitten.com/1920/1080" media="(min-width: 1440px)">
    </picture>
    

    Browser Support

    Latest Edge/FF/Chrome/Safari/iOS - see IntersectionObserver support. If you need IE support, see this polyfill.

    Install

    npm i uncloakjs

    DownloadsWeekly Downloads

    32

    Version

    1.1.9

    License

    BSD-3-Clause

    Unpacked Size

    51.5 kB

    Total Files

    8

    Last publish

    Collaborators

    • avatar