https://github.com/acusti/onscrolling

A better, smoother, more performant window.onscroll event interface using requestAnimationFrame for performance and mobile-compatibility
https://github.com/acusti/onscrolling

Last synced: 20 days ago
JSON representation

A better, smoother, more performant window.onscroll event interface using requestAnimationFrame for performance and mobile-compatibility

• Host: GitHub
• URL: https://github.com/acusti/onscrolling
• Owner: acusti
• License: cc0-1.0
• Created: 2015-04-07T15:10:44.000Z (over 9 years ago)
• Default Branch: master
• Last Pushed: 2024-09-24T01:55:08.000Z (about 2 months ago)
• Last Synced: 2024-10-14T18:07:59.429Z (about 1 month ago)
• Language: TypeScript
• Size: 460 KB
• Stars: 29
• Watchers: 3
• Forks: 2
• Open Issues: 3
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# Jank-free onscrolling  [![build workflow](https://github.com/acusti/onscrolling/actions/workflows/deploy.yml/badge.svg)](https://github.com/acusti/onscrolling/actions)

A better, smoother, more performant onscroll event interface based on the concepts from [this html5rocks tutorial][html5rocks-tutorial]. It uses `requestAnimationFrame` plus debouncing for performance and mobile-compatibility (thanks to the `touchmove` event), giving you a fighting chance to achieve the hallowed 60fps of lore with your scroll-listening UI.

[![NPM](https://nodei.co/npm/onscrolling.png?compact=true)](https://nodei.co/npm/onscrolling/)

## Usage

The module is ESM-only and exports a single default `onscrolling` function:

### onscrolling( listener )

#### `listener` function `(payload: { scrollX: number; scrollY: number }) => void`

The function to call on a scroll event with a `{ scrollX: number; scrollY: number }` payload object. In this default version, the module will only invoke the listener when the page has been scrolled vertically.

### onscrolling( listener, options )

#### `listener` function `(payload: { scrollX: number; scrollY: number }) => void`

The function to call on a scroll event with a `{ scrollX: number; scrollY: number }` payload object. The listener is invoked when the page is scrolled in any of the direction specified in the `options` object (only once per event).

#### `options` object `{ horizontal?: boolean; vertical?: boolean; x?: boolean; y?: boolean }`

The scroll axis or axes to monitor. `x` is an alias for `horizontal`, and `y` is an alias for `vertical`. If neither horizontal nor vertical are true, `vertical` is used as the default. To listen for any scroll event in any direction, set both `horizontal` and `vertical` to `true`.

### onscrolling return value

#### `onscrolling` function `(listener: Listener, options?: Options) => () => void`

The `onscrolling` function returns a cleanup function that takes no arguments and is used to remove the passed-in scroll event `listener`.

## Dependencies

None.

## Compatibility

Out of the box, onscrolling uses `requestAnimationFrame`, which is [only available in IE10+][raf-caniuse]. For older browsers, your scroll watchers simply won’t run. To add compatibility for those browsers, just include a [requestAnimationFrame polyfill][raf-polyfill].

## Tests

Tests use vitest + happy-dom, and can be run with `yarn test`.

## TODO

-   [ ] Add optional param to specify an object other than `window` to monitor for scroll events

-   [ ] Expose `measure` and `mutate` functions to attach handlers specifically to the measuring (read) or mutating (write) portion of each cycle to minimize layout calculations

## Misc

_Note: This package was formerly known as [jank-free-onscroll][]_

[html5rocks-tutorial]: http://www.html5rocks.com/en/tutorials/speed/animations/#debouncing-scroll-events

[raf-caniuse]: http://caniuse.com/#feat=requestanimationframe

[raf-polyfill]: https://gist.github.com/paulirish/1579671

[jank-free-onscroll]: https://github.com/acusti/jank-free-onscroll