How to


Reference jQuery and SpriteSpin scripts

<script src="https://code.jquery.com/jquery-3.3.1.min.js" type='text/javascript'></script>
<script src='https://unpkg.com/spritespin@4.0.3/release/spritespin.js' type='text/javascript'></script>

Create a container for SpriteSpin

<div id='mySpriteSpin'></div>

Initialize the plugin

<script type='text/javascript'>
$("#mySpriteSpin").spritespin({
  // path to the source images.
  source: [
  "path/to/frame_001.jpg",
  "path/to/frame_002.jpg",
  "path/to/frame_003.jpg",
  "path/to/frame_004.jpg",
  "path/to/frame_005.jpg",
  "path/to/frame_006.jpg",
  "path/to/frame_007.jpg",
  "path/to/frame_008.jpg",
  "path/to/frame_009.jpg",
  "path/to/frame_010.jpg",
  ],
  width   : 480,  // width in pixels of the window/frame
  height  : 327,  // height in pixels of the window/frame
});
</script>

To remove a SpriteSpin instance you have to destroy it.

// destroy the instance
$("#mySpriteSpin").spritespin("destroy")
// remove any HTML leftovers
$("#mySpriteSpin").html("")
// remove any Style leftovers
$("#mySpriteSpin").attr("style", "")

SpriteSpin Options

There are many options that can be used to initialize the plugin. Most of them are optional or have default values.

Name Type Description
animate boolean If true, starts the animation automatically on load
detectSubsampling boolean If true, tries to detect whether the images are downsampled by the browser.
frame number Initial frame number.
frames number Number of frames for a full 360 rotation.
framesX number Number of frames in one row of a single sprite sheet.
framesY number Number of frames in one column of a single sprite sheet.
frameTime number Time in ms between updates. e.g. 40 is exactly 25 FPS
height number The display height in pixels.
lane number The initial sequence number to play.
lanes number Number of sequences.
loop boolean If true, continues playback in a loop.
orientation Orientation | number Preferred axis for user interaction
plugins any[] Array of plugins to load
preloadCount number Number of images to preload. If nothing is set, all images are preloaded.
renderer RenderMode Specifies the rendering mode.
responsive boolean If true, display width can be controlled by CSS.
retainAnimate boolean If true, retains the animation after user iser interaction
reverse boolean If true, animation playback is reversed
sense number Sensitivity factor for user interaction
senseLane number Sensitivity factor for user interaction
sizeMode SizeMode Specifies how the frames are sized and scaled if it does not match the given width and height dimensions.
source string | string[] Image URL or array of urls to be used.
stopFrame number Stops the animation on that frame if `loop` is false.
target any The target element which should hold the spritespin instance. This is usually aready specified by the jQuery selector but can be overridden here.
width number The display width in pixels.
wrap boolean If true, allows the user to drag the animation beyond the last frame and wrap over to the beginning.
wrapLane boolean If true, allows the user to drag the animation beyond the last sequence and wrap over to the beginning.

Callback options

The following callback options may be used to hook into the lifecycle

Name Type Description
onComplete Callback Occurs when spritespin has been loaded and the first draw operation is complente
onDraw Callback Occurs when all update is complete and frame can be drawn
onFrame Callback Occurs when the frame number has been updated (e.g. during animation)
onFrameChanged Callback Occurs when the frame number has changed.
onInit Callback Occurs when the plugin has been initialized, but before loading the source files.
onLoad Callback Occurs when all source files have been loaded and spritespin is ready to update and draw.
onProgress Callback Occurs when any source file has been loaded and the progress has changed.

Data Object

You can access the data object that represents the state of the SpriteSpin instance and manipulate it directly.

var data = $("#mySpriteSpin").spritespin({
  // initialization options
}).data("spritespin");

The data object contains all the given options properties. Additionaly it also has the following data

Name Type Description
canvas JQuery<HTMLCanvasElement> The inner canvas element
canvasRatio number The pixel ratio of the canvas element
context CanvasRenderingContext2D The 2D context of the canvas element
frameHeight number The detected height of a single frame
frameWidth number The detected width of a single frame
id string The unique spritespin instance identifier
images HTMLImageElement[] Array of all image elements
loading boolean Is true during the preload phase
metrics SheetSpec[] Array with measurement information for each image
progress null | PreloadProgress The current preload progress state
source string[] Array of all image urls
stage JQuery The inner stage element
state any Opaque state object. Plugins may store their information here.
target JQuery The target element

API Object

SpriteSpin offers an API object that allows to register custom functions or use built in functionality.

Here is how you add a custom function

SpriteSpin.extendApi({
  myFunction: function(){
    console.log('my function simply logs the current frame', this.data.frame);
  }
});

This is how you access the api

// initialize the plugin
$("#mySpriteSpin").spritespin({ /* ... options ... */ })
// grab the api object
var api = $("#mySpriteSpin").spritespin("api");
// call your function
api.myFunction();