# sqroll

> Another scrolling library

Latest version **1.1.3** (published 2021-02-06) · MIT license · 0 weekly downloads

## Install

```sh
npm install sqroll
pnpm add sqroll
yarn add sqroll
bun add sqroll
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.1.3 |
| Published | 2021-02-06 |
| First published | 2019-02-20 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 20.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 3 |
| Author | Nicolás Arias |
| Maintainers | ezakto |
| Keywords | scroll, scrolling, viewport, trigger, track, parallax |

## Links

- npm: https://www.npmjs.com/package/sqroll
- Repository: https://github.com/ezakto/sqroll
- Issues: https://github.com/ezakto/sqroll/issues
- npm.io page: https://npm.io/package/sqroll

## Alternatives

- [@sentry/react-native](https://npm.io/package/@sentry/react-native.md) — 2.6M weekly downloads
- [@ardatan/aggregate-error](https://npm.io/package/@ardatan/aggregate-error.md) — 708.1K weekly downloads
- [custom-error-generator](https://npm.io/package/custom-error-generator.md) — 2.0K weekly downloads
- [@technik-sde/prosemirror-recreate-transform](https://npm.io/package/@technik-sde/prosemirror-recreate-transform.md) — 1.5K weekly downloads
- [@suchipi/error-utils](https://npm.io/package/@suchipi/error-utils.md) — 78 weekly downloads

## Recent versions

- 1.1.3 (latest) — 2021-02-06
- 1.1.2 — 2019-11-01
- 1.1.1 — 2019-11-01
- 1.1.0 — 2019-11-01
- 1.0.2 — 2019-10-31
- 1.0.1 — 2019-02-22
- 1.0.0 — 2019-02-20

## README

# sqroll
Sqroll is another scrolling library, with a simple api and a small overhead.

## Install

Download source or `npm install sqroll`.

Include script `dist/sqroll.min.js` as a script tag or include in source:

```js
const sqroll = require('sqroll');

import sqroll from 'sqroll';
```

You might need to polyfill `requestAnimationFrame()`.

## API & Usage

Create an instance, add triggers and then start the listener:

```js
const sq = sqroll();

// add triggers...

sq.start();
```

### sq.trigger(el, options)

This is the most basic method. It'll fire a callback function when an element hits an edge or middle of the viewport.

```js
sq.trigger(el, {
  when: 'top', // of element
  hits: 'middle', // of viewport
  callback: (el, currentScroll, direction) => {
    console.log('Click!');
  },
});
```

`when` can be `'top'`, `'middle'`, or `'bottom'`.
`hits` can also be `'top'`, `'middle'`, or `'bottom'`, or a number. If it's a number, the callback will fire when the edge/middle of the element has reached that amount of pixels.

* You can add an offset in px or vh like: 'top+100px', 'middle-50vh', 'bottom-100'.
* If only an offset is defined, default reference point is `top`: '+50px', '-10vh'.

Also, instead of `when` and `hits`, you can specify an absolute amount of scroll using `at`:

```js
sq.trigger(el, {
  at: 1000, // px
  callback: (el, currentScroll, direction) => {
    console.log('Click!');
  },
});
```

Callback is called with the element reference, the current amount of scroll and the direction the user scrolled (`'up'` or `'down'`).

By default, the callback will when the mark is passed from any direction. If you want the trigger to be called only when scrolling in one direction, pass `direction` (`'up'` or `'down'`):

```js
sq.trigger(el, {
  at: 1000, // px
  direction: 'down',
  callback: (el, currentScroll, direction) => {
    console.log('Click!');
  },
});
```

In this case, if sqroll is started with a document scroll higher than `at`, the callback will be fired immediately (for example, in a page refresh).

### sq.viewport(el, options)

This method will fire one callback every time the element enters the viewport, and one callback everytime it leaves the viewport.

```js
sq.viewport(el, {
  onIn: (el, currentScroll, direction) => {
    console.log('Visible');
  },
  onOut: (el, currentScroll, direction) => {
    console.log('Hidden');
  },
});
```

Optionally, you can add an `offset` option with one, or a space-separated pair of offsets (top and bottom), like: `offset: '100px 200px`.

### sq.track(el, options)

This will change a value from a starting point to an ending point while the user scrolls.

```js
sq.track(el, {
  start: {
    when: 'top', // of element
    hits: 'bottom', // of viewport
    value: 0,
  },
  end: {
    when: 'top',
    hits: 'top',
    value: 1,
  },
  callback: (elem, value, scroll, direction) => {
    elem.style.opacity = value;
  },
});
```

* `start` when should the callback start firing, and the initial value. In this example, when the top edge of the element is at the bottom of the viewport, the element opacity will be 0.
* `end` when should the callbacks stop, and the final value. In this example, when the top edge of the element is at the top of the viewport, the element opacity will be 1.
* `callback` gets called only if `value` is updated.

You can also use `at` property instead of `when` and `hits` to specify an absolute amount of scroll in one or both `start` and `end` objects:

```js
sq.track(el, {
  start: {
    at: 0, // px
    value: 0,
  },
  end: {
    when: 'top',
    hits: 'top',
    value: 1,
  },
  callback: (elem, value, scroll, direction) => {
    elem.style.opacity = value;
  },
});
```

### sq.start()

Start listening to scroll events and firing callbacks.

### sq.stop()

Stop listening to scroll events.

### sq.clear()

Remove all registered callbacks

### sq.destroy()

Stop listening and remove all callbacks.

---
_Source: https://npm.io/package/sqroll · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._