/react-responsive-spritesheet

React component which helps you to easily apply responsive spritesheet animations on your project.

Primary LanguageJavaScriptMIT LicenseMIT

React Responsive Spritesheet

Build Status npm npm node version Known Vulnerabilities

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.

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
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`}
/>