Animate Sprite

Demo - codepen

animate-sprite is a library (11kb without gzip) without built-in UI which allows to animate a sequence of frames that looks like 3d rotation. It supports playing full animation sequence, play specified number of frames, rotate an image by the mouse and touch; and exposes an API to programmatically control the animation.

To use it you should export animation from your 3d software as a series of frames and combine them into one image file (sprite). If you want to use a sequence of images instead of a single sprite, you could use animate-images.

• Installation
• Usage
• Options
• Methods
• Events
• Browser support
• License

Installation

Browser script tag

Add with CDN link:

<script src="https://cdn.jsdelivr.net/npm/@its2easy/animate-sprite"></script>

npm

npm i @its2easy/animate-sprite --save

Usage

Create an element with a background:

<div id="sprite" style="background-image: url('images/sprite.jpg')"></div>

Initialize with options:

let element = document.getElementById('sprite');
let sprite = new AnimateSprite(element,
    {
        width: 800, /* required */
        height: 450, /* required */
        frames: 90, /* required */
        cols: 10,
        fps: 60,
        loop: true,
        draggable: true
    }
);
sprite.play();

Or with inline options and then initialize it:

<div id="sprite" 
    style="background-image: url('images/sprite.jpg')"
    data-sprite-width="700"
    data-sprite-heigth="400"
    data-sprite-frames="45"
    data-sprite-autoplay="true"
    data-sprite-touch-scroll-mode="allowPageScroll"
></div>

let sprite = new AnimateSprite(document.getElementById('sprite'));

Inline options have higher priority

Usage with bundlers

import AnimateSprite from '@its2easy/animate-sprite';
let sprite = new AnimateSprite(element, options);

It is possible to directly import untranspiled esm version:

import AnimateSprite from '@its2easy/animate-sprite/build/untranspiled/animate-sprite.esm.js'; //or animate-sprite.esm.min.js

⚠️ You should probably add it to your build process if you use untranspiled version. Example for webpack:

rules: [
    {
        test: /\.js$/,
        exclude: /node_modules(?!(\/|\\)@its2easy(\/|\\)animate-sprite(\/|\\)build)/,
        use: {
            loader: 'babel-loader',
        }
    }
]

or

rules: [
    {
        // basic js rule
        test: /\.js$/,
        exclude: /node_modules/,
        use: {
            loader: 'babel-loader',
        }
    },
    {
        // additional rule
        test: /\.js$/,
        include: /node_modules(\/|\\)@its2easy(\/|\\)animate-sprite(\/|\\)build/,
        use: {
            loader: 'babel-loader',
    }
]

All available versions:

umd build:

@its2easy/animate-sprite/build/animate-sprite.umd.min.js - default for browser script tag and legacy bundlers

esm builds processed whit babel:

@its2easy/animate-sprite/build/animate-sprite.esm.min.js - default for webpack and module environments

@its2easy/animate-sprite/build/animate-sprite.esm.js

esm builds without babel transformation:

@its2easy/animate-sprite/build/untranspiled/animate-sprite.esm.min.js

@its2easy/animate-sprite/build/untranspiled/animate-sprite.esm.js

Responsive behavior

By default, you don't have to specify block sizes in css. Element with the sprite will take all available width and set its height based on width/height ratio from configuration options. To limit the size add max-width to the sprite. You can also explicitly set width, but it will no longer adapt to the container width (on small screens this can be changed with width: auto inside media query).

On page load sprite block will have 0px height, to prevent this you can manually add height style (and maybe backgroud-size), it will be overwritten after initialization.

Options

If multiple time options (frameTime, duration or fps) are set at the same time, frameTime has higher priority, then duration, then fps.

Methods

Methods can be chained sprite.setReverse(true).play()

new AnimateSprite(element, options)

Initializes and returns an instance of a sprite.

parameters

• element : NodeElement - dom element
• options : Object - configuration options

returns {AnimateSprite} - plugin instance

play

Start animation

returns {AnimateSprite} - plugin instance

stop

Stop animation

returns {AnimateSprite} - plugin instance

toggle

Toggle between play and stop

returns {AnimateSprite} - plugin instance

prev

Show the previous frame

returns {AnimateSprite} - plugin instance

next

Show the next frame

returns {AnimateSprite} - plugin instance

setFrame

Set frame (without animation)

parameters

• frameNumber : Number - Frame number

sprite.setFrame(35);

returns {AnimateSprite} - plugin instance

playTo

Starts the animation, that plays until the specified frame number

parameters

• frameNumber {Number} - Target frame number

// if current frame is 30 of 100, it will play from 30 to 85, 
// if current frame is 95, it will play from 95 to 85
sprite.playTo(85);

returns {AnimateSprite} - plugin instance

playFrames

Starts animation in the current direction with the specified number of frames in queue. If options.loop: false animation will stop if it reaches the first or the last frame.

parameters

• numberOfFrames {Number} - Number of frames to play

instance.playFrames(200);

returns {AnimateSprite} - plugin instance

setReverse

Change the direction of the animation

parameters

• reverse : {Boolean} - true to reverse, false to normal direction

sprite.setReverse(true);

updateSizes

Calculate new sprite and frame dimensions, should be called if element size was changes manually. updateSizes is called automatically after resize

returns {AnimateSprite} - plugin instance

getOption

Returns option value

parameters

• option {String} - Option name. All options are allowed.

let loop = instance.getOption('loop');

returns {*} - Option value

setOption

Set new option value

parameters

• option : String - Option name. All options are allowed.
• value : String|Number|Boolean - New value

sprite.setOption('frameTime', 40);

returns {AnimateSprite} - plugin instance

getCurrentFrame

Returns current frame number

returns {Number} - Frame number

isAnimating

Returns true if sprite is animating, else false

returns {Boolean}

getReverse

Returns current reverse value

returns {Boolean} - reverse

reset

Stop the animation and return to the first frame

returns {AnimateSprite} - plugin instance

destroy

Stop animation, remove event listeners. Method doesn't remove sprite element from the DOM

Events

sprite:drag-start

Fires when user starts dragging. Frame number is in event.detail.frame

sprite:drag-change

Fires on every frame change while dragging. Frame number is in event.detail.frame

sprite:drag-end

Fires when user stops dragging. Frame number is in event.detail.frame

Example:

var element = document.getElementById('sprite');
element.addEventListener('sprite:drag-end', function (event) {
    console.log(event.detail.frame);
})

Browser support

• latest versions of Chrome, android Chrome, Edge, Firefox
• Safari 13.1+,
• iOS Safari 13.4+

License

Animate Sprite is provided under the MIT License