# raf-plus

> better requestAnimationFrame

Latest version **0.0.9** (published 2017-07-17) · MIT license · 0 weekly downloads

## Install

```sh
npm install raf-plus
pnpm add raf-plus
yarn add raf-plus
bun add raf-plus
```

## Health

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

Positive: no vulnerabilities.

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

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.9 |
| Published | 2017-07-17 |
| First published | 2017-07-04 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 69 |
| Author | joezheng |
| Maintainers | joezheng |
| Keywords | requestAnimationFrame, management, better-requestAnimationFrame |

## Links

- npm: https://www.npmjs.com/package/raf-plus
- Repository: https://github.com/weiying-shenzhen/raf-plus
- Homepage: https://github.com/weiying-shenzhen/raf-plus#readme
- Issues: https://github.com/weiying-shenzhen/raf-plus/issues
- npm.io page: https://npm.io/package/raf-plus

## Alternatives

- [@luma.gl/experimental](https://npm.io/package/@luma.gl/experimental.md) — 77.1K weekly downloads
- [persona-harness](https://npm.io/package/persona-harness.md) — 4.7K weekly downloads
- [@tsparticles/effect-bubble](https://npm.io/package/@tsparticles/effect-bubble.md) — 4.6K weekly downloads
- [f3d](https://npm.io/package/f3d.md) — 730 weekly downloads
- [spark-html-motion](https://npm.io/package/spark-html-motion.md) — 298 weekly downloads

## Recent versions

- 0.0.9 (latest) — 2017-07-17
- 0.0.8 — 2017-07-12
- 0.0.7 — 2017-07-10
- 0.0.6 — 2017-07-09
- 0.0.5 — 2017-07-08
- 0.0.4 — 2017-07-08
- 0.0.3 — 2017-07-08
- 0.0.2 — 2017-07-05
- 0.0.1 — 2017-07-04

## README

# raf-plus

[![Build Status](https://travis-ci.org/weiying-shenzhen/raf-plus.svg?branch=master)](https://travis-ci.org/weiying-shenzhen/raf-plus)

raf-plus is `window.requestAnimationFrame` with queue management, which will only invokes the passed function at most once per animation frame.

可观看[中文文档](https://github.com/weiying-shenzhen/raf-plus/blob/master/README_zh.md)

## Reason

> Also note that multiple calls to requestAnimationFrame with the same callback (before callbacks are invoked and the list is cleared) will result in multiple entries being in the list with that same callback, and thus will result in that callback being invoked more than once for the animation frame.
> -- [w3c](https://www.w3.org/TR/animation-timing/#dom-windowanimationtiming-requestanimationframe)

For example:

```js
const animation = () => {
    // A animation function
}

document.addEventListener('scroll', e => requestAnimationFrame(animation), false)
```

The scroll event may fire more than once within one frame, so the `animation` function may be called more than once before next repaint, but repetitively call `animation` at one animation frame is unnecessary and waste of resources!!!

The raf-plus help you manage requestAnimationFrame's queue by ignoring the duplicate callback function in same animation frame. For comparison:

```js
import { requestAnimationFrame } from 'raf-plus'
const animationTwice = () => console.log('I will be invoked twice!')
const animationOnce = () => console.log('Although call twice, I will be invoked once')

// call same animation within one animation frame lead to animation twice
window.requestAnimationFrame(animationTwice)
window.requestAnimationFrame(animationTwice)

// call same animation within one animation frame but only invoke once
requestAnimationFrame(animationOnce)
requestAnimationFrame(animationOnce)
```

## Install

```bash
$ npm install --save raf-plus
```
or
```bash
$ yarn add raf-plus
```

## Usage

The raf-plus provides two methods `requestAnimationFrame` and `cancelAnimationFrame`. They keep the same API as `window.requestAnimationFrame` and `window.cancelAnimationFrame`. Therefore, It is costless to switch from native's to raf-plus's.

### `requestAnimationFrame(callback)`

The same as [requestAnimationFrame](https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame). Be aware that raf-plus uses === operator to compare two callbacks, so passing anonymous function won't invoke the management!

```js
const { requestAnimationFrame } from 'raf-plus'

const animation = timeStamp => {
    // animation
}

// animation will be invoked once within one frame
requestAnimationFrame(animation)
requestAnimationFrame(animation)

// animation will be invoked twice cause the function are not equal
requestAnimationFrame(timeStamp => { /* animation */})
requestAnimationFrame(timeStamp => { /* animation */})
```

### `cancelAnimationFrame(requestID)`

The same as [cancelAnimationFrame](https://developer.mozilla.org/en-US/docs/Web/API/Window/cancelAnimationFrame).

```js
const { requestAnimationFrame, cancelAnimationFrame } from 'raf-plus'

const animation = timeStamp => {
    // animation
}
const requestId = requestAnimationFrame(animation)
cancelAnimationFrame(requestId)
```

## Contributing

- ⇄ Pull requests and ★ Stars are always welcome.
- For bugs and feature requests, please create an issue.

## Licence

MIT

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