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 Name	Type	Description
`player.currentTime`	Integer	current animation time in milliseconds
`player.direction`	Integer	New: animation direction (1 == normal, -1 == reverse)
`player.duration`	Integer	the duration of one loop in milliseconds
`player.fill`	Integer	New: animation fill mode (1 for forwards, -1 for backwards); if set to -1, animation will jump to its start once finished
`player.fps`	Integer	New: Frame per seconds (default: 100)
`player.hasEnded`	Boolean	true if the animation reached to the ended
`player.isAlternate`	Boolean	true if the animation is set to alternate mode
`player.isBackwards`	Boolean	New: true if fill mode is set to backwards (-1)
`player.isInfinite`	Boolean	New: true if the animation is set to infinite loop
`player.isPlaying`	Boolean	true if the animation is currently playing
`player.isReversed`	Boolean	New: true if the direction of the animation is set to reversed
`player.isRollingBack`	Boolean	true if the animation is rolling back
`player.iterations`	Integer	the number of iterations or 0 for infinite playing
`player.speed`	Float	New: animation speed as floating number, 1 representing 100% (normal speed)
`player.state`	String / Enum	player status; one of the following: ["playing", "paused", "ended", "rollback"]
`player.totalTime`	Integer	Total 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 Name	Param.	Triggers Event	Description
`.play()`	n/a	`play`	plays the current animation from current offset or restarts if it has ended
`.pause()`	n/a	`pause`	Pauses the current animation.
`.restart()`	n/a	`restart`	Restarts the animation from its beginning.
`.reverse()`	n/a	`reverse`	Reverses the playing direction and plays the animation.
`.toggle()`	n/a	`play` or `pause`	Toggles between play and pause.
`.togglePlay()`	n/a	`play` or `pause`	New: Alias for `toggle`
`.stop()`	n/a	`stop`	Stops the current animation and resets it to the first keyframe.
`.ready(callback)`	Function	n/a	Calls `callback` when the `player` is ready, passing the `player` as 1st parameter. read more
`.seek(offsetPercent)`	Float	n/a	Advances 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)`	Integer	n/a	Advances the animation with `offsetMs` milliseconds. Negative values are also allowed.
`.seekTo(offsetMs)`	Integer	n/a	Advances the animation to `offsetMs` milliseconds
`.set(property, value)`	String, Mixed	n/a	New: Sets writable properties
`.destruct()`	n/a	`stop`	Detaches 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.

Property	Type	Values	Description
`alternate`	Boolean	`true` \| `false`	Switches alternate mode on or off; applies only for more iterations. Sample call: `player.set('alternate', true)`
`direction`	Integer	`-1` \| `1`	sets direction to normal (1) or reverse (-1)
`fill`	Integer	`-1` \| `1`	sets fill mode to forwards (1) or backwards (-1)
`fps`	Integer	`1` to `100`	sets frames per second (actual frames per seconds might be lower, depending on hardware)
`iterations`	Integer	`0` to `Infinity`	sets the number of iterations, 0 representing inifinite animations
`speed`	Float	`0` to `100`	sets 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 )

Parameter	Type	Description
`eventName`	String	The name of the event(s) to listen to Multiple events are allowed, separated by space or comma sample value: `start, restart`
`fn`	Function	Event handler function Inside the function, `this` will refer to the API object the handler will receive the current `offset` as its first parameter
`prepend`	Boolean	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])

Parameter	Type	Description
`eventName`	String	The name of the event to remove listeners from listen to Multiple events are not allowed sample value: `start`
`fn`	Function	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.

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.