Quovadis NPM | npm.io

Quovadis

Quovadis is a lightweight JavaScript library to facilitate dealing with changes in scroll-direction. It is based on the scroll-intent plugin by pwfisher with some key differences:

no jQuery dependency 🙅‍♂️
offers automatic orientation detection 🔮
allows setting of a custom scroll target element 🎯
allows targetting horizontal scroll ↔️
sets classes on the html element instead of data-attributes ✌️
dispatches scrollDirectionChange event when scroll-direction changes 🚨

Have any suggestions or feedback? Reach out!

Installation

Install via npm

npm install quovadis

Download and include via script tag

<script src="quovadis.min.js"></script>

Using `import` statement

import Quovadis from "quovadis";

Usage

JS

Initialize Quovadis by creating a new Quovadis instance.

var q = new Quovadis();
q.attach();

Quovadis accepts a list of options. Passing no options (as in the example above) defaults to:

var q = new Quovadis({
  context: document.documentElement,
  horizontal: false,
  event: true,
  historyLength: 32,
  historyMaxAge: 512,
  thresholdPixels: 64,
});

Output

By default, Quovadis will automatically add and remove classes on the html element based on scroll direction, i.e. scrolling-down and scrolling-up or scrolling-right and scrolling-left when working in horizontal mode.

Event

Unless set to do otherwise, Quovadis will also dispatch a scrollDirectionChange event to the window element. This event can be used to set up your own callback functions to fire once scroll direction changes.

window.addEventListener("scrollDirectionChange", function (e) {
  switch (e.detail.direction) {
    case "up":
      /* stuff to do when scrolling up */
      break;
    case "down":
      /* stuff to do when scrolling down */
      break;
    case "left":
      /* stuff to do when scrolling left */
      break;
    case "right":
      /* stuff to do when scrolling right */
      break;
  }
});

Options

Property	Type	Description	Default
`context`	Element	Sets the element to listen to scroll events on.	`window`
`horizontal`	Boolean/String	Set this to `true` to explicitly target horizontal scrolling. In `auto` mode, Quovadis will try to figure out the orientation on its own.	`'auto'`
`event`	Boolean	Determines whether Quovadis should fire a `scrollDirectionChange` event when scroll direction changes.	`true`
`debug`	Boolean	Enables debug mode which will output information about the currently active Quovadis instance to the console.	`false`
`historyLength`	Number	The number of records to keep to determine the scroll direction.	`32`
`historyMaxAge`	Number	The maximum duration for a record to determine the scroll direction.	`512`
`thresholdPixels`	Number	The number of pixels to scroll before re-evaluating the direction	`64`

Methods

Method	Description
`attach()`	Initializes the Quovadis instance. This is also the function that returns the EventListener for the scroll context.
`detach()`	Removes the EventListener from the Quovadis instance.
`reattach(el)`	Attaches the Quovadis EventListener to a new scroll context. This is useful when working with dynamic AJAX content. Accepts an element parameter.