vivus

# vivus.js Demo available on http://maxwellito.github.io/vivus Play with it on [Vivus Instant](https://maxwellito.github.io/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](https://www.npmjs.com/package/vivus): `npm install vivus` - [Bower](http://bower.io/): `bower install vivus` - [jsDelivr CDN](http://www.jsdelivr.com/#!vivus): `//cdn.jsdelivr.net/npm/vivus@latest/dist/vivus.min.js` - [CDNJS CDN](https://cdnjs.com/libraries/vivus) - [WebJars](http://www.webjars.org/) Join the conversation on [Gitter](https://gitter.im/maxwellito/vivus) Try Vivus with your SVG on [Vivus Instant](https://maxwellito.github.io/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](https://github.com/maxwellito/vivus/issues/22) for more details. The code is inspired from other repositories. The drawer is inspired from the excellent [Codrops](http://tympanus.net/codrops/) about the post [SVG Drawing Animation](http://tympanus.net/codrops/2013/12/30/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](https://github.com/Waest/SVGPathConverter) by [Waest](https://github.com/Waest). ## Usage As I said, no dependencies here. All you need to do is include the scripts. **Inline SVG** ```html ``` **Dynamic load** ```html ``` or ```html ``` 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: ```js 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](https://github.com/maxwellito/vivus/blob/master/hacks.md) 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](#timing-function). | | `animTimingFunction` | function | Timing animation function for the complete SVG. Check the [timing function part](#timing-function). | | `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: `false`] | | `selfDestroy` | boolean | Removes all extra styling on the SVG, and leaves it as original. | ### 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. ```js 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. ```js const myVivus = new Vivus('my-svg-id'); myVivus.play(1, function () { // called after the animation completes }); // alternativly if you leave the speed param blank and use the default, you // can pass the callback as the first parameter like so. myVivus.play(function () { // called after the animation completes }); ``` ## Timing function To give more freedom, it's possible to override the animation of each path and/or the entire SVG. It works a bit like the