@datarose/scrollreveal NPM

Datarose Production

scrollreveal

Information

This package upgraded version of original scrollreveal (v3.4.0) created by jlmakes.

Documentation

Note: Documentation links will working after open to Documentation content.

Getting Started

Installation

Using File

  <!-- Import () -->
  <script type="module" src="https://unpkg.com/@datarose/scrollreveal"></script>
  <script type="module">
    // Regardless of the method of import, in our examples used dSR variable.
    const dSR = window.DataroseScrollReveal();
  </script>

  ... or ...

  <script type="module">
    // Import (ES2015)
    import DataroseScrollReveal from 'https://unpkg.com/@datarose/scrollreveal';

    // Regardless of the method of import, in our examples used dSR variable.
    const dSR = DataroseScrollReveal();
  </script>

Help: This will create DataroseScrollReveal as global variable. Warning: Be careful using this method in production. Without specifying a fixed version number, Unpkg may delay your page load while it resolves the latest version. Learn more at unpkg.com. If you dont want delay loading, can set static versioned link - ex. https://unpkg.com/@datarose/scrollreveal@x.x.x -, but this can't upgrade yourself automatically.

Using Module

  # Install
  npm install @datarose/scrollreveal

  // Import (ES2015)
  import DataroseScrollReveal from '@datarose/scrollreveal'
  // ... or ...
  // Import (CommonJS)
  const DataroseScrollReveal = require('@datarose/scrollreveal')

  // Regardless of the method of import, in our examples used dSR variable.
  const dSR = DataroseScrollReveal();

The Basics

The reveal() method is the primary API, and makes it easy to create and manage various types of animations.

  <!-- HTML -->
  <div class="foo">Foo</div>
  <div class="bar">Bar</div>

  // JavaScript
  // Generate new object
  const dSR = DataroseScrollReveal();
  // Add animations for object
  dSR.reveal('.foo');
  dSR.reveal('.bar');

Configuration

Passing a configuration object to DataroseScrollReveal() changes the defaults for all reveals, and passing reveal() a configuration object customizes that reveal set further.

Practical Example

How to can change defaults

  // Changing the defaults
  const dSR = DataroseScrollReveal({ reset: true });

  // Customizing a reveal set
  dSR.reveal('.foo', { duration: 200 });

The Starting Defaults

What is default parameters

  // 'bottom', 'left', 'top', 'right'
  origin: 'bottom',

  // Can be any valid CSS distance, e.g. '5rem', '10%', '20vw', etc.
  distance: '20px',

  // Time in milliseconds.
  duration: 500,
  delay: 0,

  // Starting angles in degrees, will transition from these values to 0 in all axes.
  rotate: { x: 0, y: 0, z: 0 },

  // Starting opacity value, before transitioning to the computed opacity.
  opacity: 0,

  // Starting scale value, will transition from this value to 1
  scale: 0.9,

  // Accepts any valid CSS easing, e.g. 'ease', 'ease-in-out', 'linear', etc.
  easing: 'cubic-bezier(0.6, 0.2, 0.1, 1)',

  // `<html>` is the default reveal container. You can pass either:
  // DOM Node, e.g. document.querySelector('.fooContainer')
  // Selector, e.g. '.fooContainer'
  container: window.document.documentElement,

  // true/false to control reveal animations on mobile.
  mobile: true,

  // true:  reveals occur every time elements become visible
  // false: reveals occur once as elements become visible
  reset: false,

  // 'always' — delay for all reveal animations
  // 'once'   — delay only the first time reveals occur
  // 'onload' - delay only for animations triggered by first load
  useDelay: 'always',

  // Change when an element is considered in the viewport. The default value
  // of 0.20 means 20% of an element must be visible for its reveal to occur.
  viewFactor: 0.2,

  // Pixel values that alter the container boundaries.
  // e.g. Set `{ top: 48 }`, if you have a 48px tall fixed toolbar.
  viewOffset: { top: 0, right: 0, bottom: 0, left: 0 },

  // Callbacks that fire for each triggered element reveal, and reset.
  beforeReveal: function (domEl) {},
  beforeReset: function (domEl) {},

  // Callbacks that fire for each completed element reveal, and reset.
  afterReveal: function (domEl) {},
  afterReset: function (domEl) {}

Advanced

Sequenced Animations

You can pass a sequence interval (in milliseconds) to the reveal() method, making sequenced animations a breeze.

Note: The interval is the time until the next element in the sequence begins its reveal, which is separate from the time until the element’s animation completes. In this example, the animation duration is 2 seconds, but the sequence interval is 50 milliseconds.

Examples (2)

  // interval passed to reveal
  const dSR = DataroseScrollReveal({ duration: 2000 });
  dSR.reveal('.box', 50);

  // or...

  // interval and custom config passed to reveal
  const dSR = DataroseScrollReveal();
  dSR.reveal('.box', { duration: 2000 }, 50);

sequencer

Working With DOM Nodes

You may also pass Node, NodeList and Array<Node> as the reveal target.

Example (1)

  var node = document.querySelector('.foo');
  var nodeList = document.querySelectorAll('.bar');
  var array = Array.prototype.slice.call(nodeList);

  dSR.reveal(node);
  dSR.reveal(nodeList);
  dSR.reveal(array);

Custom/Multiple Containers

The default container is the viewport, but you can assign any container to any reveal set.

Tip: ScrollReveal works just as well with horizontally scrolling containers too!

Example (1)

  <div id="fooContainer">
    <div class="foo">Foo 1</div>
    <div class="foo">Foo 2</div>
    <div class="foo">Foo 3</div>
  </div>

  <div id="barContainer">
    <div class="bar">Bar 1</div>
    <div class="bar">Bar 2</div>
    <div class="bar">Bar 3</div>
  </div>

  const dSR = DataroseScrollReveal();

  // as a DOM node...
  var fooContainer = document.getElementById('fooContainer');
  dSR.reveal('.foo', { container: fooContainer });

  // as a selector...
  dSR.reveal('.bar', { container: '#barContainer' });

Asynchronous Content

The sync() method updates asynchronously loaded content with any existing reveal sets.

Example (1)

  <!-- index.html -->
  <div id="fooContainer">
    <div class="foo">foo</div>
    <div class="foo">foo</div>
    <div class="foo">foo</div>
  </div>

  <!-- ajax.html -->
  <div class="foo">foo async</div>
  <div class="foo">foo async</div>
  <div class="foo">foo async</div>

  var fooContainer, content, sr, xmlhttp;

  fooContainer = document.getElementById('fooContainer');

  const dSR = DataroseScrollReveal();
  dSR.reveal('.foo', { container: fooContainer });

  // Setup a new asynchronous request...
  xmlhttp = new XMLHttpRequest();
  xmlhttp.onreadystatechange = function() {
    if (xmlhttp.readyState == XMLHttpRequest.DONE) {
      if (xmlhttp.status == 200) {

        // Turn our response into HTML...
        var content = document.createElement('div');
        content.innerHTML = xmlhttp.responseText;
        content = content.childNodes;

        // Add each element to the DOM...
        for (var i = 0; i < content.length; i++) {
          fooContainer.appendChild(content[ i ]);
        };

        // Finally!
        dSR.sync();
      }
    }
  }

  xmlhttp.open('GET', 'ajax.html', true);
  xmlhttp.send();

Tips

Improve User Experience

In most cases, your elements will start at opacity: 0 so they can fade in. However, since JavaScript loads after the page begins rendering, you might see your elements flickering as they begin rendering before being hidden by ScrollReveal's JavaScript.

The ideal solution is to set your reveal elements visibility to hidden in the <head> of your page, to ensure they render hidden while your JavaScript loads:

Example (1)

  <!DOCTYPE html>
  <html>
  <head>
    <script>
      import DataroseScrollReveal from '@datarose/scrollreveal';
      const dSR = DataroseScrollReveal();

      // Add class to <html> if ScrollReveal is supported
      if (dSR.isSupported()) {
        document.documentElement.classList.add('dSR');
      }
    </script>
    <style>
      /* Ensure elements load hidden before ScrollReveal runs */
      .dSR .fooReveal { visibility: hidden; }
    </style>
  </head>
  <body>
    <div class="fooContainer">
      <div class="fooReveal">Foo</div>
      <div class="fooReveal">Foo</div>
      <div class="fooReveal">Foo</div>
    </div>

    <!-- make reveal calls last -->
    <script>
      dSR.reveal('.fooReveal', { container: '.fooContainer' });
    </script>
  </body>
  </html>

Note: If you prefer not to put styles in the <head> of your page, including this style in your primary stylesheet will still help with element flickering since your CSS will likely load before your JavaScript.

Add Perspective to 3D Rotation

ScrollReveal supports 3d rotation out of the box, but you may want to emphasize the effect by specifying a perspective property on your container.

Example (1)

  <!DOCTYPE html>
  <html>
  <head>
    <script>
      import DataroseScrollReveal from '@datarose/scrollreveal';
      const dSR = DataroseScrollReveal();

      // Add class to <html> if ScrollReveal is supported
      if (dSR.isSupported()) {
        document.documentElement.classList.add('dSR');
      }
    </script>

    <style>
      /* Ensure elements load hidden before ScrollReveal runs */
      .dSR .fooReveal { visibility: hidden; }

      /* add perspective to your container */
      .fooContainer { perspective: 800px; }
    </style>
  </head>

  <body>
    <div class="fooContainer">
      <div class="fooReveal">Foo</div>
      <div class="fooReveal">Foo</div>
      <div class="fooReveal">Foo</div>
    </div>

    <!-- make reveal calls last -->
    <script>
      // use rotation in reveal configuration
      dSR.reveal('.fooReveal', { container: '.fooContainer', rotate: {x: 65} });
    </script>
  </body>
  </html>

Appendix

License

@datarose/scrollreveal

jlmakes/scrollreveal (v3.4.0)

Browser Compatibility

ScrollReveal works on any JavaScript enabled browser that supports both CSS Transform and CSS Transition. This includes Internet Explorer 10+, and most modern desktop and mobile browsers.