quovadis

A small library to handle changes in scroll direction.

Usage no npm install needed!

<script type="module">
  import quovadis from 'https://cdn.skypack.dev/quovadis';
</script>

README

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.