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
import
statement
Using 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.