quovadis
Version:
A small library to handle changes in scroll direction.
110 lines (81 loc) • 4.82 kB
Markdown
# Quovadis
Quovadis is a lightweight JavaScript library to facilitate dealing with changes in scroll-direction. It is based on the [scroll-intent](https://github.com/pwfisher/scroll-intent.js) plugin by [pwfisher](https://github.com/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!](mailto:mail@timjuedemann.de)
## Installation
### Install via npm
```js
npm install quovadis
```
### Download and include via script tag
```html
<script src="quovadis.min.js"></script>
```
or
### Using `import` statement
```jss
import Quovadis from "quovadis";
```
## Usage
### JS
Initialize Quovadis by creating a new Quovadis instance.
```js
var q = new Quovadis();
q.attach();
```
Quovadis accepts a list of options. Passing no options (as in the example above) defaults to:
```js
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.
```js
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.