SVGator Player JS API

This document describes SVGator JS API properties, methods and the Event interface as well as demonstrates usage through a Live Demo. To learn more about how to access the Player object and how to synchronize events, see our post about how to animate programmatically.

I. Live Demo

II. Player Properties

Property NameTypeDescription
player.currentTimeIntegercurrent animation time in milliseconds
player.directionIntegerNew: animation direction (1 == normal, -1 == reverse)
player.durationIntegerthe duration of one loop in milliseconds
player.fillIntegerNew: animation fill mode (1 for forwards, -1 for backwards); if set to -1, animation will jump to its start once finished
player.fpsIntegerNew: Frame per seconds (default: 100)
player.hasEndedBooleantrue if the animation reached to the ended
player.isAlternateBooleantrue if the animation is set to alternate mode
player.isBackwardsBooleanNew: true if fill mode is set to backwards (-1)
player.isInfiniteBooleanNew: true if the animation is set to infinite loop
player.isPlayingBooleantrue if the animation is currently playing
player.isReversedBooleanNew: true if the direction of the animation is set to reversed
player.isRollingBackBooleantrue if the animation is rolling back
player.iterationsIntegerthe number of iterations or 0 for infinite playing
player.speedFloatNew: animation speed as floating number, 1 representing 100% (normal speed)
player.stateString / Enumplayer status; one of the following: ["playing", "paused", "ended", "rollback"]
player.totalTimeIntegerTotal animation time if it is finite ( = iterations x duration); duration for infinite animations

III. Player Methods

Each player.method() call returns the player API object itself.

Action NameParam.Triggers EventDescription
.play()n/aplayplays the current animation from current offset or restarts if it has ended
.pause()n/apausePauses the current animation.
.restart()n/arestartRestarts the animation from its beginning.
.reverse()n/areverseReverses the playing direction and plays the animation.
.toggle()n/aplay orpauseToggles between play and pause.
.togglePlay()n/aplay orpauseNew: Alias for toggle
.stop()n/astopStops the current animation and resets it to the first keyframe.
.ready(callback)Functionn/aCalls callback when the player is ready, passing the player as 1st parameter. read more
.seek(offsetPercent)Floatn/aAdvances the animation to offset in %, where offset must be a float between 0 and 100. player.seek(50) will advance the animation to 50%
.seekBy(offsetMs)Integern/aAdvances the animation with offsetMs milliseconds. Negative values are also allowed.
.seekTo(offsetMs)Integern/aAdvances the animation to offsetMs milliseconds
.set(property, value)String, Mixedn/aNew: Sets writable properties
.destruct()n/astopDetaches the player object from the SVG, removes event handlers, stops the animation & resets to the first keyframe. Further API calls will not have any effect.

IV. Writable Properties

The properties listed below can be set thorough a player.set(property, value) call, which returns the player API object itself.

PropertyTypeValuesDescription
alternateBooleantrue | falseSwitches alternate mode on or off; applies only for more iterations. Sample call: player.set('alternate', true)
directionInteger-1 | 1sets direction to normal (1) or reverse (-1)
fillInteger-1 | 1sets fill mode to forwards (1) or backwards (-1)
fpsInteger1 to 100sets frames per second (actual frames per seconds might be lower, depending on hardware)
iterationsInteger0 to Infinitysets the number of iterations, 0 representing inifinite animations
speedFloat0 to 100sets the speed of the animation, 1 representing 100% and 0.5 representing 50% of the original duration

V. Player Events

There are 2 dedicated methods for attaching and detaching event handlers:

Attaching Events

player.on( eventName, fn, prepend = false )
ParameterTypeDescription
eventNameString
  • The name of the event(s) to listen to
  • Multiple events are allowed, separated by space or comma
  • sample value: start, restart
fnFunction
  • Event handler function
  • Inside the function, this will refer to the API object
  • the handler will receive the current offset as its first parameter
prependBoolean
  • If set to true, handler will be added to the beginning of the handler list

Example:

player.on( 'pause',
	offset => console.log(`Animation paused at offset ${offset}.`)
);

Detaching Events

player.off( eventName[, fn])
ParameterTypeDescription
eventNameString
  • The name of the event to remove listeners from listen to
  • Multiple events are not allowed
  • sample value: start
fnFunction
  • Handler function to remove from current event
  • Optional; if none given, all listeners will be removed from the current event

Example:

player.off( 'pause');

Available Events:

  • play
  • pause
  • restart
  • reverse
  • stop

Please refer to the table of API actions to see when the 5 events above are triggered. To be noted that they are triggered from user actions as well, not only from API calls (i.e. if the animation starts on click).

  • end

This event is triggered when the animation reaches to the end.

  • keyframe

The keyframe special event is triggered with each frame applied. As for the other event handlers, the first argument of the handler function is the offset (in milliseconds) the frames are applied to.


More articles:

Animate Programmatically

Export Settings

Still got questions? Send us an email at contact@svgator.com and we will get back to you as soon as we can.