MorphSVGPlugin

MorphSVGPlugin provides advanced control over tweens that morph SVG paths. The video below details what you need to know to get up and running fast with MorphSVGPlugin.

It has never been easier to morph between SVG shapes. First, let's cover what this new plugin can do:

  • Morph <path> data even if the number (and type) of points is completely different between the start and end shapes! Most other SVG shape morphing tools require that the number of points matches.
  • Morph a <polyline> or <polygon> to a different set of points
  • There's a utility function, MorphSVGPlugin.convertToPath() that can convert primitive shapes like <circle>, <rect>, <ellipse>, <polygon>, <polyline>, and <line> directly into the equivalent <path> that looks identical to the original and is swapped right into the DOM.
  • Optionally define a "shapeIndex" that controls how the points get mapped. This affects what the inbetween state looks like during animation.
  • Instead of passing in raw path data as text, you can simply feed in selector text or an element and the plugin will grab the data it needs from there, making workflow easier.
  • Use MorphSVGPlugin.pathDataToBezier() to seamlessly feed SVG path data into BezierPlugin tweens for motion along a path.

How does it work?

MorphSVGPlugin does a ton of heavy lifting so that you don't have to. You can morph a circle into a hippo with a single line of code:

TweenLite.to("#circle", 1, {morphSVG:"#hippo"});

MorphSVGPlugin finds the path with the id of "circle" and the path with the id of "hippo" and automatically figures out how to add enough points to the circle and position them properly so that you get a super smooth transition to the hippo shape. It will rip through all that ugly path data, convert everything to cubic beziers, and dynamically subdivide them when necessary, adding points so that the beginning and ending quantities match (but visually it looks the same). It’s all seamless under the hood, of course.

Note: MorphSVGPlugin requires GSAP 1.18.0 (TweenLite or TweenMax)

API

MorphSVGPlugin needs to know what shape to morph too and optionally which shapeIndex to use.

When only specifying a shape, MorphSVGPlugin can take a wide range of values.

Selector string

TweenLite.to("#circle", 1, {morphSVG:"#hippo"});

An SVG element

var endShape = document.getElementById("hippo");
TweenLite.to("#circle", 1, {morphSVG:endShape);

Points for <polyline> or <polygon> elements:

TweenLite.to(“#polygon”, 2, {morphSVG:"240,220 240,70 70,70 70,220"});

Strings for <path> elements

TweenLite.to(“#path”, 2, {morphSVG:"M10 315 L 110 215 A 30 50 0 0 1 162.55 162.45 L 172.55 152.45 A 30 50 -45 0 1 215.1 109.9 L 315 10"});

*Note: if the shape you pass in is a <rect>, <circle>, <ellipse> (or similar), MorphSVGPlugin will internally create path data from those shapes.

shapeIndex

The shapeIndex property allows you to adjust how the points in the start shape are mapped. In order to prevent points from drifting wildly during the animation MorphSVGPlugin needs to find a point in the start path that is in close proximity to the first point in the end path. Once that point is found it will map the next point in the start path to the second point in the end path (and so on and so on). Due to the complexity of vector art there will be times that you may want to change which point in the start path gets mapped to the first point in the end path. This is where shapeIndex comes in.

In order to specify the shapeIndex you need to use an object {} with shape and shapeIndex properties.

The following code will map the third point in the square to the first point in the star.

TweenLite.to("#square", 1, {morphSVG:{shape:"#star", shapeIndex:3}});

findShapeIndex() utility

Experimenting with shapeIndex can be a bit of a guessing game. To make things easier we have created a stand-alone utility function called findShapeIndex(). This function provides an interactive user interface to help you visualize where the start point is, change it and preview the animation.

You can load findShapeIndex() from: https://s3-us-west-2.amazonaws.com/s.cdpn.io/16327/findShapeIndex.js

Once its loaded you simply tell it which shapes to use.

findShapeIndex("#square", "#star");

Or pass in raw data:

findShapeIndex("#square", "M10 315 L 110 215 A 30 50 0 0 1 162.55 162.45 L 172.55 152.45 A 30 50 -45 0 1 215.1 109.9 L 315 10");

The best way to get started is to drop your SVG into the pen above and alter the IDs to match your svg. Be sure to watch the video above which clearly illustrates how shapeIndex and findShapeIndex() work.

Additional Notes

  • shapeIndex only works on closed paths.
  • if you supply a negative shapeIndex the start path will be completely reversed (which can be quite useful).

Performance tip #1: define a shapeIndex in advance

MorphSVGPlugin's default shapeIndex:"auto" does a bunch of calculations to reorganize the points so that they match up in a natural way but if you define a numeric shapeIndex (like shapeIndex:5) it skips those calculations. Each segment inside a path needs a shapeIndex, so multiple values are passed in an array like shapeIndex:[5,1,-8,2]. But how would you know what numbers to pass in? The findShapeIndex() tool helps for single-segment paths, what about multi-segment paths? It's a pretty complex thing to provide a GUI for.

Typically the default "auto" mode works great but the goal here is to avoid the calculations, so there is a new "log" value that will act just like "auto" but it will also console.log() the shapeIndex value(s). That way, you can run the tween in the browser once and look in your console and see the numbers that "auto" mode would produce. Then it's simply a matter of copying and pasting that value into your tween where "log" was previously. For example:

TweenMax.to("#id", 1, {morphSVG:{shape:"#otherID", shapeIndex:"log"}}); //logs a value like "shapeIndex:[3]"
//now you can grab the value from the console and drop it in...
TweenMax.to("#id", 1, {morphSVG:{shape:"#otherID", shapeIndex:[3]}});

Converting SVG shapes to paths


Technically it’s only feasible to morph <path> elements or <polyline>/<polygon> elements, but what if you want to morph a <circle> or <rect> or <ellipse> or <line>? No problem - just tap into the utility method and have the plugin do the conversion for you:

MorphSVGPlugin.convertToPath("#elementID");


You can pass in an element or selector text, so you could also have it convert ALL of those elements with one line:

MorphSVGPlugin.convertToPath("circle, rect, ellipse, line, polygon, polyline");


This literally swaps in a for each one directly in the DOM, and it should look absolutely identical. It’ll keep the attributes, like the “id” attribute. So after the conversion, you should be able to target the elements pretty easily, just as you would before.

//An svg  Like this:

//becomes

Morph into multiple shapes

Since MorphSVGPlugin is so tightly integrated into GSAP, sequencing multiple morphs is a breeze. Watch how easy it is to make that circle morph into a hippo, star, elephant and back to a circle.

tl.to(circle, 1, {morphSVG:"#hippo"}, "+=1")
  .to(circle, 1, {morphSVG:"#star"}, "+=1")
  .to(circle, 1, {morphSVG:"#elephant"}, "+=1")
  .to(circle, 1, {morphSVG:circle}, "+=1");

Note: MorphSVG 0.5.0+ stores the original path data on any target of a morph tween so that you can easily tween back to the original shape.

data-original="M490.1,280.649c0,44.459-36.041,80....">

Performance tip #2: precompile

The biggest performance improvement comes from precompiling which involves having MorphSVGPlugin run all of its initial calculations listed above and then spit out an array with the transformed strings, logging them to the console where you can copy and paste them back into your tween. That way, when the tween begins it can just grab all the values directly instead of doing expensive calculations. For example:

TweenMax.to("#id", 1, {morphSVG:{shape:"#otherID", precompile:"log"}}); //logs a value like precompile:["M0,0 C100,200 120,500 300,145 34,245 560,46","M0,0 C200,300 100,400 230,400 100,456 400,300"]
//now you can grab the value from the console and drop it in...
TweenMax.to("#id", 1, {morphSVG:{shape:"#otherID", precompile:["M0,0 C100,200 120,500 300,145 34,245 560,46","M0,0 C200,300 100,400 230,400 100,456 400,300"]}});

As an example, here's a really cool codepen by Dave Rupert before it was precompiled: http://codepen.io/davatron5000/pen/meNOqK/. Notice the very first time you click the toggle button, it may seem to jerk a bit because the entire brain is one path with many segments, and it must get matched up with all the letters and figure out the shapeIndex for each (expensive). By contrast, here's a fork of that pen that has precompile enabled: http://codepen.io/GreenSock/pen/MKevzM. You may noticed that it starts more smoothly.

Notes

  • precompile was added in MorphSVGPlugin version 0.8.1.
  • precompile is only available on <path> elements (not polyline/polygon). You can easily convert things using MorphSVGPlugin.convertToPath("polygon, polyline");
  • Precompiling only improves the performance of the first (most expensive) render. If your entire morph is janky throughout the tween, it most likely has nothing to do with GSAP; your SVG may be too complex for the browser to render fast enough. In other words, the bottleneck is probably the browser's graphics rendering routines. Unfortunately, there's nothing GSAP can do about that and you'll need to simplify your SVG artwork and/or reduce the size at which it is displayed.
  • The precompiled values are inclusive of shapeIndex adjustments. In other words, shapeIndex gets baked in.
  • In most cases, you probably don't need to precompile; it's intended to be an advanced technique for squeezing every ounce of performance out of a very complex morph.
  • If you alter the original start or end shape/artwork, make sure you precomple again so that the values reflect your changes.

Controlling segment matching

In version 0.8.1, there were several improvements made to the algorithm that matches up corresponding segments in the start and end shapes so that things just look more natural. So even without changing any of your code, loading the latest version may instantly make things match up better.

map: "size" | "position" | "complexity"

If the sub-segments inside your path aren't matching up the way you hoped between the start and end shapes, you can use the map special property to tell MorphSVGPlugin which algorithm to prioritize:

  • "size" (the default) - attempts to match segments based on their overall size. If multiple segments are close in size, it'll use positional data to match them. This mode typically gives the most intuitive morphs.
  • "position" - matches mostly based on position.
  • "complexity" - matches purely based on the quantity of anchor points. This is the fastest algorithm and it can be used to "trick" things to match up by manually adding anchors in your SVG authoring tool so that the pieces that you want matched up contain the same number of anchors (though that's completely optional).
TweenMax.to("#id", 1, {morphSVG:{shape:"#otherID", map:"complexity"}});

Notes

  • map is completely optional. Typically the default mode works great.
  • If none of the map modes get the segments to match up the way you want, it's probabaly best to just split your path into multiple paths and morph each one. That way, you get total control.

Animate along an SVG path

The new MorphSVGPlugin.pathDataToBezier() method converts SVG <path> data into an array of cubic Bezier points that can be fed directly into a BezierPlugin-based tween so that you can essentially use it as a motion guide.

Watch the video

Demo

Performance Tips Video

The video below shows exactly how to implement the performance tips above regarding shapeIndex:log and precompile:log.

MorphSVGPlugin Examples

Get your hands on MorphSVGPlugin

MorphSVGPlugin is a bonus plugin for Club GreenSock members ("Shockingly Green" and higher). It's our way of saying "Thank you" to those that are fueling innovation at GreenSock. To download MorphSVGPlugin, just log into your account dashboard and grab the latest version of GSAP.

Try MorphSVGPlugin for free on Codepen!
There's a special [fully-functional] version of MorphSVGPlugin that we link to in our demos in our MorphSVGPlugin Collection on CodePen, so feel free to fork any of them, add your own SVG graphics, and take MorphSVGPlugin for a spin. Codepen is a fantastic way to experiment. We highly recommend it. Note: the special version of the plugin will only work on the Codepen domain.

To find out more about the many benefits of being a Club GreenSock member swing on by the club page and be sure to check out the other premium plugins.

MorphSVG and other bonus plugins are not hosted on a CDN. Checkout our CDN FAQs for more info.

Methods

convertToPath( shape:* ) : Array

Converts SVG shapes like <circle>, <rect>, <ellipse>, or <line> into <path>

pathDataToBezier( path:*, vars:Object ) : Array

Converts SVG <path> data into an array of cubic Bezier points that can be fed directly into a BezierPlugin-based tween.

Copyright 2017, GreenSock. All rights reserved. This work is subject to theterms of useor for Club GreenSock members, the software agreement that was issued with the membership.

Get GSAP

Version: 2.0.2 updated 2018-08-27

Core

    Extras

      Plugins

        By using GreenSock code, you agree to the terms of use.

        Help support GreenSock by becoming a member

        Join Club GreenSock