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>

or

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. |

License

This project is licensed under the MIT License.