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