vivus.js

Demo available on http://maxwellito.github.io/vivus

Play with it on Vivus Instant

Vivus is a lightweight JavaScript class (with no dependencies) that allows you to animate SVGs, giving them the appearance of being drawn. There are a variety of different animations available, as well as the option to create a custom script to draw your SVG in whatever way you like.

Available via:

• NPM: npm install vivus
• Bower: bower install vivus
• jsDelivr CDN: //cdn.jsdelivr.net/npm/vivus@latest/dist/vivus.min.js
• CDNJS CDN
• WebJars

Join the conversation on Gitter

Try Vivus with your SVG on Vivus Instant. If you plan to use the library to animate a single SVG without callback or controls, this will allow you to download your animated SVG, powered by CSS, JavaScript free.

Animations

On the following images, the pink color represents the duration value, and the blue one is for delay value.

Delayed

Every path element is drawn at the same time with a small delay at the start. This is currently the default animation.

Sync

Each line is drawn synchronously. They all start and finish at the same time, hence the name sync.

OneByOne

Each path element is drawn one after the other. This animation gives the best impression of live drawing. The duration for each line depends on their length to make a constant drawing speed.

Principles

To get this effect, the script uses the CSS property strokeDashoffset. This property manages the stroke offset on every line of the SVG. Now, all we have to do is add some JavaScript to update this value progressively and the magic begins.

However, there's a problem with this. The strokeDashoffset property is only available on the path elements. This is an issue because in an SVG there are a lot of elements such as circle, rect, line and polyline which will break the animation. So to fix this, there is another class available in the repo called pathformer. It's made for transforming all objects of your SVG into path elements to be able to use strokeDashoffset and animate your SVGs.

The animation always draws elements in the same order as they are defined in the SVG tag.

There are few conditions that your SVG must meet:

• All elements must have a stroke property and cannot be filled. This is because the animation only looks to progressively draw strokes and will not check for filled colours. For example: fill: "none"; stroke: "#FFF";

• You should avoid creating any hidden path elements in your SVG. Vivus considers them all eligible to be animated, so it is advised to remove them before playing with it. If they are not removed the animation might not achieve the desired effect, with blank areas and gaps appearing.

• text elements aren't allowed, they cannot be transformed into path elements. See #22 for more details.

The code is inspired from other repositories. The drawer is inspired from the excellent Codrops about the post SVG Drawing Animation (if you don't know this website, get ready to have your mind blown). Then for the pathformer, there is a lot of work from SVGPathConverter by Waest.

Usage

As I said, no dependencies here. All you need to do is include the scripts.

Inline SVG

<svg id="my-svg">
  <path...>
  <path...>
  <path...>
</svg>

<script>
  new Vivus('my-svg', {duration: 200}, myCallback);
</script>

Dynamic load

<object id="my-svg" type="image/svg+xml" data="link/to/my.svg"></object>

<script>
  new Vivus('my-svg', { duration: 200 }, myCallback);
</script>

or

<div id="my-div"></div>

<script>
  new Vivus('my-div', { duration: 200, file: 'link/to/my.svg' }, myCallback);
</script>

By default the object created will take the size of the parent element, this one must have a height and width or your SVG might not appear.

If you need to edit this object, it is accessible in the onReady callback:

new Vivus('my-div-id', {
  file: 'link/to/my.svg',
  onReady: function (myVivus) {
    // `el` property is the SVG element
    myVivus.el.setAttribute('height', 'auto');
  }
});

Check out the hacks page for more tricks.

Constructor

The Vivus constructor asks for 3 parameters:

• ID (or object) of DOM element to interact with.It can be an inline SVG or a wrapper element to append an object tag from the option file
• Option object (described in the following |
• Callback to call at the end of the animation (optional)

Option list

Name	Type	Description
type	string	Defines what kind of animation will be used: delayed, sync, oneByOne, script, scenario or scenario-sync. [Default: delayed]
file	string	Link to the SVG to animate. If set, Vivus will create an object tag and append it to the DOM element given to the constructor. Be careful, use the onReady callback before playing with the Vivus instance.
start	string	Defines how to trigger the animation (inViewport once the SVG is in the viewport, manual gives you the freedom to call draw method to start, autostart makes it start right now). [Default: inViewport]
duration	integer	Animation duration, in frames. [Default: 200]
delay	integer	Time between the drawing of first and last path, in frames (only for delayed animations).
onReady	function	Function called when the instance is ready to play.
pathTimingFunction	function	Timing animation function for each path element of the SVG. Check the timing function part.
animTimingFunction	function	Timing animation function for the complete SVG. Check the timing function part.
dashGap	integer	Whitespace extra margin between dashes. Increase it in case of glitches at the initial state of the animation. [Default: 2]
forceRender	boolean	Force the browser to re-render all updated path items. By default, the value is true on IE only. (check the 'troubleshoot' section for more details).
reverseStack	boolean	Reverse the order of execution. The default behaviour is to render from the first 'path' in the SVG to the last one. This option allow you to reverse the order. [Default: ]

Methods

Name	Description
play(speed, callback)	Plays the animation with the speed given in parameter. This value can be negative to go backward, between 0 and 1 to go slowly, >1 to go faster, or <0 to go in reverse from current state. [Default: 1]. Callback executed after the animation is finished (optional)
stop()	Stops the animation.
reset()	Reinitialises the SVG to the original state: undrawn.
finish()	Set the SVG to the final state: drawn.
setFrameProgress(progress)	Set the progress of the animation. Progress must be a number between 0 and 1.
getStatus()	Get the status of the animation between start, progress, end
destroy()	Reset the SVG but make the instance out of order.

These methods return the object so you can chain the actions.

const myVivus = new Vivus('my-svg-id');
myVivus.stop().reset().play(2);

Play method callback

Instead of using the global constructor callback when you create the Vivus object, you can add callbacks to be executed for specific play method calls.

const myVivus = new Vivus('my-svg-id');
myVivus.play(1, function () {
  // called after the animation completes
});

// alternativly if you lea