A React higher-order component for managing recurring animation frames

by React

React Animation Frame

A React higher-order component for invoking component repeating logic using requestAnimationFrame. It works in both the browser and React Native.

The module follows the CommonJS format, so it is compatible with Browserify and Webpack. It also supports ES5 and beyond.

Motivation

Take a look at the example project; this contains a Timer component that should animate a progress bar until the configured end time is surpassed:

'use strict';

const React = require('react');
const ReactAnimationFrame = require('react-animation-frame');

class Timer extends React.Component {
    onAnimationFrame(time) {
        const progress = Math.round(time / this.props.durationMs * 100);
        this.bar.style.width = `${progress}%`;

        if (progress === 100) {
            this.props.endAnimation();
        }
    }

    render() {
        return (
            <div className="timer">
                <p>{this.props.message}</p>
                <div className="timer__bar" ref={node => this.bar = node}></div>
            </div>
        );
    }
}

module.exports = ReactAnimationFrame(Timer);

The onAnimationFrame method will be called on each repaint, via requestAnimationFrame, by the higher-order ReactAnimationFrame component. Once the progress of our animation reaches 100%, we can kill the underlying loop using the endAnimation method passed to the props of the wrapped component.

The loop can also be throttled by passing a second parameter to ReactAnimationFrame, which represents the number of milliseconds that should elapse between invocations of onAnimationFrame:

module.exports = ReactAnimationFrame(Timer, 100);

Installation

npm i --save react-animation-frame

API

ReactAnimationFrame(Component[, throttleMs])

Wraps Component and starts a requestAnimationFrame loop. throttleMs if specified, will throttle invocations of onAnimationFrame by any number of milliseconds.

Inside a wrapped component

onAnimationFrame(timestamp, lastTimestamp)

Called on each iteration of the underlying requestAnimationFrame loop, or if the elapsed throttle time has been surpassed. timestamp is the same DOMHighResTimeStamp with which requestAnimationFrame's callback is invoked.

The previous timestamp is also passed, which can be useful for calculating deltas. For n calls, lastTimestamp will be the value of timestamp for call n - 1.

this.props.endAnimation()

Cancels the current animation frame and ends the loop.

this.props.startAnimation()

Function to restart the animation after it was ended by endAnimation.

Local development

Run npm i to install the dependencies.

  • npm run build - transpile the library
  • npm test - lints the code and runs the tests

GitHub