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
- ForwardRef usage
- 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

`bash
$ npm install react-responsive-spritesheet --save
`


----------




Usage

Basic usage with required parameters

`javascript
import Spritesheet from 'react-responsive-spritesheet';

class App extends Component {

render() {

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

}

}
`

Complete usage with all parameters

`javascript
import Spritesheet from 'react-responsive-spritesheet';

class App extends Component {

render() {

return (
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

`javascript
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

`javascript
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

`javascript
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

`javascript
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:

`javascript
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:

`javascript



`

`javascript
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

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

----------

ForwardRef usage

You can control the spritesheet instance directly using a React ref. The component supports forwardRef, so ref.current exposes the same instance methods available in callbacks.

JavaScript (function component)

`jsx
import React, { useRef } from 'react';
import Spritesheet from 'react-responsive-spritesheet';

export default function Example() {
const spriteRef = useRef(null);

return (



);
}
`

TypeScript (function component, typed ref)

`tsx
import React, { useRef } from 'react';
import Spritesheet from 'react-responsive-spritesheet';

type SpritesheetRef = React.ComponentRef;

export default function ExampleTs() {
const spriteRef = useRef(null);

const handleToggle = () => {
if (!spriteRef.current) return;
const isPlaying = spriteRef.current.getInfo('isPlaying');
isPlaying ? spriteRef.current.pause() : spriteRef.current.play();
};

return (



);
}
`

Class component

`jsx
import React from 'react';
import Spritesheet from 'react-responsive-spritesheet';

class ExampleClass extends React.Component {
spriteRef = React.createRef();

render() {
return (



);
}
}
`

Notes:
- The ref exposes methods like play, pause, goToAndPlay, goToAndPause, setStartAt, setEndAt, setFps, setDirection, and getInfo.
- getInstance continues to work; choose either ref or getInstance` based on your preference.

----------