React component which helps you to easily apply responsive spritesheet animations

React Responsive Spritesheet

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

View demo Download Source

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

React Responsive Spritesheet

Installation

Usage

Options

Call methods

Requesting infos

Examples

GitHub