React Responsive Spritesheet

Hello, world!

React Responsive Spritesheet is a React component which helps you to easily apply responsive spritesheet animations on your project. See our basic example.

• Installation
• Usage
• Options
• Call methods
• Requesting infos
• Examples

New version 2 available!

• Now you can use horizontal, vertical or multi-row spritesheet image;
• Orientation parameter is no longer required;
• Spritesheet image is preloaded before initialization;
• The animation can be rewinded with setDirection() method and/or with direction parameter;
• Direction information is provided by getInfo() method;

For previous versions, see our release history

Installation

$ npm install react-responsive-spritesheet --save

Usage

Basic usage with required parameters

import Spritesheet from 'react-responsive-spritesheet';

class App extends Component {

  render() {

    return (
      <Spritesheet
        image={`http://www.example.com/assets/image.png`}
        widthFrame={800}
        heightFrame={648}
        steps={46}
        fps={12}
      />
    );

  }

}

Complete usage with all parameters

import Spritesheet from 'react-responsive-spritesheet';

class App extends Component {

  render() {

    return (
      <Spritesheet
        className={`my-element__class--style`}
        style={{ backgroundColor: 'red' }}
        image={`http://www.example.com/assets/image.png`}
        widthFrame={800}
        heightFrame={648}
        steps={46}
        fps={12}
        direction={`forward`}
        timeout={1800}
        autoplay={false}
        loop={true}
        startAt={10}
        endAt={30}
        background={`http://www.example.com/assets/image.png`}
        backgroundSize={`cover`}
        backgroundRepeat={`no-repeat`}
        backgroundPosition={`center center`}
        getInstance={spritesheet => {
          this.spriteInstance = spritesheet;
        }}
        onClick={spritesheet => {
          spritesheet.play();
        }}
        onDoubleClick={spritesheet => {
          console.log( spritesheet.getInfo('isPlaying') );
        }}
        onMouseMove={spritesheet => {
          console.log( 'onMouseMove', spritesheet.getInfo('frame') );
        }}
        onMouseEnter={spritesheet => {
          console.log('onMouseEnter');
        }}
        onMouseLeave={spritesheet => {
          console.log('onMouseLeave');
        }}
        onMouseOver={spritesheet => {
          console.log('onMouseOver');
        }}
        onMouseOut={spritesheet => {
          console.log('onMouseOut');
        }}
        onMouseDown={spritesheet => {
          console.log('onMouseDown');
        }}
        onMouseUp={spritesheet => {
          console.log('onMouseUp');
        }}
        onInit={spritesheet => {
          console.log('onInit');
        }}
        onResize={spritesheet => {
          console.log( 'onResize', spritesheet.getInfo('frame') );
        }}
        onPlay={spritesheet => {
          console.log('onPlay');
        }}
        onPause={spritesheet => {
          console.log('onPause');
        }}
        onLoopComplete={spritesheet => {
          console.log('onLoopComplete');
        }}
        onEachFrame={spritesheet => {
          console.log('onEachFrame');
        }}
        onEnterFrame={[
          {
            frame: 2,
            callback: (() => {
              console.log('passed by frame 2')
            })
          },
          {
            frame: 7,
            callback: (() => {
              console.log('passed by frame 7')
            })
          }
        ]}
      />
    );

  }

}

Options

| Required | Parameter | Type | Example | Description | | :------------: | ------------ | ------------ | ------------ | ------------ | | | className | string | 'my-element__class--style' | Applies a classname for spritehseet container | | | style | object | { backgroundColor: 'red', display: 'flex' } | Applies inline style for spritehseet container | | ✓ | image | string | 'http://yyy.com/image.png' | URL or path of image to animate | | ✓ | widthFrame | number | 800 | Original width of each frame, in pixels | | ✓ | heightFrame | number | 800 | Original height of each frame, in pixels | | ✓ | steps | number | 47 | Total frames / steps present on animation image | | ✓ | fps | number | 12 | Velocity / Animation frames per second | | ✓ | direction | string | 'rewind' | 'forward' or 'rewind' direction to display frames. It allows rewind the animation. Default: 'forward' | | | timeout | number | 1200 | Delay for start animating. The 'autoplay' option must be true | | | autoplay | boolean | false | Determines if animation starts automatically | | | loop | boolean | false | Determines if animation replay on end | | | isResponsive | boolean | true | Determines if animation resizes according window resize | | | startAt | number | false | Determines the first frame which will be displayed on start to animate | | | endAt | number | false | Determines the last frame which will be displayed on stop animation | | | background | string | '/assets/background.png' | URL or path of background image placed behind animation | | | backgroundSize | string | 'cover' | Style for background image | | | backgroundRepeat | string | 'no-repeat' | Style for background image | | | backgroundPosition | string | 'center center' | Style for background image | | | getInstance | callback | | Returns callback instance for spritesheet controls | | | onClick | function | | Provides onClick callback function for spritesheet container | | | onDoubleClick | function | | Provides onDoubleClick callback function for spritesheet container | | | onMouseMove | function | | Provides onMouseMove callback function for spritesheet container | | | onMouseEnter | function | | Provides onMouseEnter callback function for spritesheet container | | | onMouseLeave | function | | Provides onMouseLeave callback function for spritesheet container | | | onMouseOver | function | | Provides onMouseOver callback function for spritesheet container | | | onMouseOut | function | | Provides onMouseOut callback function for spritesheet container | | | onMouseDown | function | | Provides onMouseDown callback function for spritesheet container | | | onMouseUp | function | | Provides onMouseUp callback function for spritesheet container | | | onInit | function | | Provides callback function when the spritesheet initializes | | | onResize | function | | Provides callback function when the spritesheet resizes | | | onPlay | function | | Provides callback function when the spritesheet plays. spritesheet.goToAndPlay(x) method also fires this callback | | | onPause | function | | Provides callback function when the spritesheet pauses. spritesheet.goToAndPause(x) method also fires this callback | | | onLoopComplete | function | | Provides callback function when the animation completes a loop cicle | | | onEachFrame | function | | Provides callback function when each animation frame is changed | | | onEnterFrame | array | | Accepts an array of callback functions when the specific animation frame is displayed |

Call methods

Using the instance provided on callback functions you can call some methods

Example

onMouseEnter={spritesheet => {
  console.log( spritesheet.setStartAt(6) );
}}

| Method | Call | Description | | ------------ | ------------ | ------------ | | play | spritesheet.play() | Plays the animation from current frame | | pause | spritesheet.pause() | Pauses the animation on current frame | | goToAndPlay | spritesheet.goToAndPlay(frameNumber) | Plays the animation from specified frame as argument | | goToAndPause | spritesheet.goToAndPause(frameNumber) | Pauses the animation on specified frame | | setStartAt | spritesheet.setStartAt(frameNumber) | Sets the first frame to be displayed on animation starts. It will be considered on loop cycles. | | setEndAt | spritesheet.setEndAt(frameNumber) | Sets the last frame to be displayed on animation ends. It will be considered on loop cycles. | | setFps | spritesheet.setFps(fpsNumber) | Sets the fps (speed) of animation, even while is playing | | setDirection | spritesheet.setDirection('rewind') | Sets the direction of animation forward or rewind | | getInfo | spritesheet.getInfo('stringInfoToRetrieve') | Returns some real-time information about spritesheet. See below on Requesting infos section |

Requesting infos

Using the instance.getInfo(x) method provided on callback functions you can request a real-time information about your spritesheet animation

Example

onMouseEnter={spritesheet => {
  console.log( spritesheet.getInfo('frame') );
}}

| Parameter | Type | Returns | | ------------ | ------------ | ------------ | | frame | number | current frame of animation | | fps | number | current frames per second (speed) | | steps | number | total number of animation steps | | width | number | scaled animation width, in pixels | | height | number | scaled animation height, in pixels | | scale | number | scale of spritesheet, based on default sizes, note that scale=1 is relative to original size | | direction | string | direction 'forward' or 'rewind' playing | | isPlaying | boolean | if animation is currently playing, returns true | | isPaused | boolean | if animation is currently paused or stopped, returns true | | completeLoopCicles | number | total number of cycles (loops) the animation has completed |

Examples

Example #1 A basic usage with minimal parameters for spritesheet animation loop starting automatically.

live demo / edit source code

<Spritesheet
  className={`my-element__class--style`}
  image={`https://raw.githubusercontent.com/danilosetra/react-responsive-spritesheet/master/assets/images/examples/sprite-image-horizontal.png`}
  widthFrame={420}
  heightFrame={500}
  steps={14}
  fps={10}
  autoplay={true}
  loop={true}
/>

Example #2 Using parameters onMouseEnter and onMouseLeave for play and pause animation

live demo / edit source code

<Spritesheet
  className={`my-element__class--style`}
  image={`https://raw.githubusercontent.com/danilosetra/react-responsive-spritesheet/master/assets/images/examples/sprite-image-horizontal.png`}
  widthFrame={420}
  heightFrame={500}
  steps={14}
  fps={10}
  autoplay={false}
  loop={true}
  onMouseEnter={spritesheet => {
    spritesheet.play();
  }}
  onMouseLeave={spritesheet => {
    spritesheet.pause();
  }}
/>

Example #3

Using spritesheet instance to controls outside parameters, on your own functions.

live demo / edit source code

First, we use getInstance parameter to get instance and set this.spritesheetInstance to be used on your whole component, see below:

<Spritesheet
  className={`my-element__class--style`}
  image={`https://raw.githubusercontent.com/danilosetra/react-responsive-spritesheet/master/assets/images/examples/sprite-image-horizontal.png`}
  widthFrame={420}
  heightFrame={500}
  steps={14}
  fps={10}
  autoplay={false}
  loop={true}
  getInstance={spritesheet => {
    this.spritesheeInstance = spritesheet;
  }}
/>

Then, we can create buttons or whatever and set their own functions:

<div>
  <button onClick={this.myFunctionPlay.bind(this)}>play</button>
  <button onClick={this.myFunctionPause.bind(this)}>pause</button>
  <button onClick={this.myFunctionGetFrame.bind(this)}>alert current frame</button>
  <button onClick={this.myFunctionToggleDirection.bind(this)}>toggle direction</button>
</div>

myFunctionPlay(){
  this.spritesheeInstance.play();
}

myFunctionPause(){
  this.spritesheeInstance.pause();
}

myFunctionGetFrame(){
  alert(this.spritesheeInstance.getInfo('frame'));
}

myFunctionToggleDirection(){
  if(this.spritesheeInstance.getInfo('direction') === 'forward'){
    this.spritesheeInstance.setDirection('rewind');
  } else if(this.spritesheeInstance.getInfo('direction') === 'rewind'){
    this.spritesheeInstance.setDirection('forward');
  }
}

Example #4 Using background image

live demo / edit source code

<Spritesheet
  className={`my-element__class--style`}
  image={`https://raw.githubusercontent.com/danilosetra/react-responsive-spritesheet/master/assets/images/examples/sprite-image-horizontal.png`}
  widthFrame={420}
  heightFrame={500}
  steps={14}
  fps={10}
  autoplay={true}
  loop={true}
  background={`https://raw.githubusercontent.com/danilosetra/react-responsive-spritesheet/master/assets/images/examples/sprite-image-background.png`}
  backgroundSize={`cover`}
  backgroundRepeat={`no-repeat`}
  backgroundPosition={`center center`}
/>