Spritz.js

📽Modern and delightful sprites animation library for JavaScript!

Can be used for interactive animations, 360 viewers, HTML5 games, and more...

✨ Try the Demo samples.

Features

• Lightweight - under 3.3KB minified and gzipped.
• Responsive - syntax following the new HTML5 picture element.
• Modern - written in ES6 JavaScript, no jQuery required.
• Compatible - IE10+ support, mobile support.
• Chainable API - play, pause, wait, and more...

Getting Started

1. Installation
2. Usage
3. Options
4. API / Methods
5. Events
6. Browser Support
7. Contribute
8. Projects using it!
9. License

Installation

Using Yarn

yarn add spritz.js

Using NPM

npm i spritz.js --save

Unpkg CDN

<script src="https://unpkg.com/[email protected]/dist/spritz.js"></script>

Usage

The sprite will be generated inside the HTML element passed as first parameter. The canvas dimensions will depend on the width and the height of this element.

<div id="#selector"></div>

// import the library
import Spritz from 'spritz.js'

// instantiate with options
const sprite = Spritz('#selector', { /* options here */ })

// 🎉 ready to control your sprite!
sprite.play().wait(2000).pause()

Options

Settings overview list:

Spritz('#selector', {
	picture: [],
	steps: 1,
	rows: 1
})

Full option details are detailed below.

| Option | Type | Default | Description | | --- | --- | --- | --- | | picture | array | [] | Array of picture objects to be used as Sprite. The syntax is close to the new HTML5 picture element. More details below. | | steps | integer | 1 | Number of steps (or frames) composing the sprite. | | rows | integer | 1 | Number of rows (or lines) composing the sprite. | | init | integer | 1 | Initial sprite step. Set to false to disable the default auto‑init() feature. |

Sprite object will be displayed as per background-size .

Picture

The picture option syntax is close to the new HTML5 picture element. The library will choose the most suitable source according to the current layout of the page and the browser it will be displayed into. Sense of reading is following the array order (first to last element).

Parameters:

| Key | Type | Description | | --- | --- | --- | | srcset | required | Accepts a single image file path (e.g. srcset: 'kitten.png'). WebP format accepted for compatible browsers (built-in detection). | | media | optional | Accepts any valid media query that you would normally find in a CSS @media selector (e.g. media: '(max-width: 1200px)'). | | width | required | Specify the full width in pixels, of the sprite source image (e.g. width: 7800). | | height | required | Specify the full width in pixels, of the sprite source image (e.g. height: 2829). | | objectFit | optional | Specifies how the sprite should be fitted to the parent. Values: contain or cover. Default: contain. |

Example:

[
	{
		srcset: 'kitten-highres.png',
		media: '(min-width: 1200px)',
		objectFit: 'cover',
		width: 7800, height: 2829
	},
	{
		srcset: 'kitten.webp',
		width: 3900, height: 1415
	},
	{
		srcset: 'kitten.png',
		width: 3900, height: 1415
	}
]

API

Spritz exposes the following chainable API methods.

Basic methods

• fps
• play
• playback
• pause
• stop
• wait
• step
• next
• prev

Advanced methods

• init
• destroy
• until
• flip
• get

.fps()

Change animation speed from its default value (15).

sprite.fps(10) // Change speed to 10fps

.play()

Play animation forward (using the current fps value). A backward option can be passed as parameter.

sprite.play()
sprite.play('backward') // Alternative way to play an animation backward

.playback()

Play animation backward (using the current fps value).

sprite.playback()

.pause()

Pause the current animation.

sprite.pause()

.stop()

Stop the current animation (pause and reset to the initial step).

sprite.stop()

.wait()

Chainable timeout that can be used to delay stuff. The delay value is to be passed as parameter, in milliseconds.

sprite.wait(1000) // Wait for 1 second

/* Usage example */
sprite
	.play() // Play animation
	.wait(2000) // Then wait for 2 second
	.stop() // Then stop animation

.step()

Change the current step (or frame) of the sprite. Target step to be passed as parameter.

sprite.step(5) // Change current step/frame to 5

.next()

Go to the next step (or frame).

sprite.next()

.prev()

Go to the previous step (or frame).

sprite.prev()

.init()

Build and load the sprite, within its selector. Initial step can be passed as parameter.

sprite.init() // Basic usage
sprite.init(2) // Initial step is 2 (default = 1)

.destroy()

Completely destroy the sprite element and behaviors. Restore the initial state.

sprite.destroy()

.until()

The next animation will automatically pause at the value specified. Two parameters can be used:

• step (required): Step/frame at which the animation should stop.
• loop (optional, default 1): Loop at which the animation should stop.

sprite.until(7) // Animation will automatically stop at step/frame 7
sprite.until(3, 2) // Animation will automatically stop at step/frame 3, on the second loop

/* Usage example */
sprite
	.until(7) // Stop following animation at step/frame 7
	.play() // Play animation (will automatically stop at step/frame 7)

.flip()

Flip the sprite horizontally.

sprite.flip()

.get()

Return data, then call the callback function with result. Two parameters can be used:

• data (required): Data to return. Possible values: step| picture.
• callback (optional): Callback function to be called with result as first parameter.

// console log the current step/frame
sprite.get('step', (currentStep) => {
	console.log(currentStep)
})

// console log the current picture in use
sprite.get('picture', (pic) => {
	console.log(pic)
})

Note that this method, like the others, is chainable.

Events

The following events can be used to write custom callbacks functions.

// Sprite is ready for use (after init)
sprite.on('ready', () => { /* Your code here */ })

// Sprite image has been loaded (current 'picture' loaded passed as parameter)
sprite.on('load', (picture) => { /* Your code here */ })

// Sprite has been destroyed
sprite.on('destroy', () => { /* Your code here */ })

// Sprite animation start ('forward' or 'backward' passed as first parameter)
sprite.on('play', (direction) => { /* Your code here */ })

// Sprite animation pause
sprite.on('pause', () => { /* Your code here */ })

// Sprite animation stop
sprite.on('stop', () => { /* Your code here */ })

// Animation timeout delay in  progress ('delay' value passed as parameter)
sprite.on('wait', (delay) => { /* Your code here */ })

// Step changed manually ('from' and 'to' passed as parameters)
sprite.on('change', (from, to) => { /* Your code here */ })

// Viewport has been resized (new current 'picture' passed as parameter)
sprite.on('resize', (picture) => { /* Your code here */ })

Browser Support

Fully supported by Evergreen Browsers (Edge, Opera, Safari, Firefox & Chrome) and IE 10+ browsers.

For older browsers support like IE8 or IE9, you'll need to manually include the following Polyfill library on your website:

<script src="https://cdn.polyfill.io/v2/polyfill.min.js"></script>

Contribute

yarn run watch
yarn run test

License

MIT © 2017-2019 Sylvain Simao