https://github.com/danilosetra/react-responsive-spritesheet
React component which helps you to easily apply responsive spritesheet animations on your project.
https://github.com/danilosetra/react-responsive-spritesheet
animation animations npm react responsive spritesheet
Last synced: 4 months ago
JSON representation
React component which helps you to easily apply responsive spritesheet animations on your project.
- Host: GitHub
- URL: https://github.com/danilosetra/react-responsive-spritesheet
- Owner: danilosetra
- License: mit
- Created: 2017-08-31T18:46:01.000Z (almost 9 years ago)
- Default Branch: master
- Last Pushed: 2025-12-10T15:20:20.000Z (7 months ago)
- Last Synced: 2025-12-10T16:20:47.804Z (7 months ago)
- Topics: animation, animations, npm, react, responsive, spritesheet
- Language: TypeScript
- Size: 742 KB
- Stars: 99
- Watchers: 3
- Forks: 18
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# React Responsive Spritesheet
[](https://snyk.io/test/github/danilosetra/react-responsive-spritesheet) [](https://travis-ci.org/danilosetra/react-responsive-spritesheet) [](https://npmjs.org/package/r`eact-responsive-spritesheet) [](https://npmjs.org/package/react-responsive-spritesheet) [](http://nodejs.org/download/)
## Hello, world!
React Responsive Spritesheet is a [React](https://facebook.github.io/react/) component which helps you to easily apply responsive spritesheet animations on your project. See our [basic example](https://stackblitz.com/edit/react-responsive-spritesheet-example-01?file=index.js).
- [Installation](#installation)
- [Usage](#usage)
- [Options](#options)
- [Call methods](#call-methods)
- [Requesting infos](#requesting-infos)
- [ForwardRef usage](#forwardref-usage)
- [Examples](#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 tags](https://github.com/danilosetra/react-responsive-spritesheet/tags)
----------
## 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 (
);
}
}
```
**Complete usage with all parameters**
```javascript
import Spritesheet from 'react-responsive-spritesheet';
class App extends Component {
render() {
return (
{
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](#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](https://react-responsive-spritesheet-example-01.stackblitz.io/) / [edit source code](https://stackblitz.com/edit/react-responsive-spritesheet-example-01?file=index.js)
```javascript
```
----------
**Example #2**
Using parameters **onMouseEnter** and **onMouseLeave** for play and pause animation
[live demo](https://react-responsive-spritesheet-example-02.stackblitz.io/) / [edit source code](https://stackblitz.com/edit/react-responsive-spritesheet-example-02?file=index.js)
```javascript
{
spritesheet.play();
}}
onMouseLeave={spritesheet => {
spritesheet.pause();
}}
/>
```
----------
**Example #3**
Using spritesheet instance to controls outside parameters, on your own functions.
[live demo](https://react-responsive-spritesheet-example-03.stackblitz.io/) / [edit source code](https://stackblitz.com/edit/react-responsive-spritesheet-example-03?file=index.js)
First, we use **getInstance** parameter to get instance and set **this.spritesheetInstance** to be used on your whole component, see below:
```javascript
{
this.spritesheeInstance = spritesheet;
}}
/>
```
Then, we can create buttons or whatever and set their own functions:
```javascript
play
pause
alert current frame
toggle direction
```
```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](https://react-responsive-spritesheet-example-04.stackblitz.io/) / [edit source code](https://stackblitz.com/edit/react-responsive-spritesheet-example-04?file=index.js)
```javascript
```
----------
## 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 (
spriteRef.current && spriteRef.current.play()}>play
spriteRef.current && spriteRef.current.pause()}>pause
spriteRef.current && spriteRef.current.goToAndPlay(5)}>go to 5 & play
);
}
```
**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 (
toggle play/pause
spriteRef.current?.setDirection('rewind')}>rewind
spriteRef.current?.setFps(24)}>set fps to 24
);
}
```
**Class component**
```jsx
import React from 'react';
import Spritesheet from 'react-responsive-spritesheet';
class ExampleClass extends React.Component {
spriteRef = React.createRef();
render() {
return (
this.spriteRef.current && this.spriteRef.current.play()}>play
this.spriteRef.current && this.spriteRef.current.pause()}>pause
);
}
}
```
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.
----------