MorphSVGPlugin

MorphSVGPlugin morphs SVG paths by animating the data inside the "d" attribute. The video explains more...

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.
• Draw the resulting shape to <canvas> (via a render function or set a MorphSVGPlugin.defaultRender )
• Use either linear interpolation (the default) or a newer "rotational" type to get more natural looking morphs
• 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 to get a super smooth morph. 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.

API

MorphSVGPlugin needs to know what shape to morph to 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.

Type (rotational or linear)

By default, all of the anchors and control points in the shape are interpolated linearly (type:"linear") which is usually fine but you can set type:"rotational" to make MorphSVG use rotation and length data for interpolation instead which can produce more natural morphs in some cases. It also completely eliminates any kinks that may form in otherwise smooth anchors mid-tween. The concept is best understood visually, so here are some videos and demos...

To tap into this new style of morphing, just set type:"rotational" in the object:

TweenMax.to("#shape1", 2, {
    morphSVG:{
        shape:"#shape2",
        type:"rotational"
    }
});

Interactive comparison of linear and rotational morphs

Custom origins and findMorphOrigin()

To set your own origin:

TweenMax.to("#shape1", 2, {
    morphSVG:{
        shape:"#shape2",
        type:"rotational",
        origin:"20% 60%" //or "20% 60%,35% 90%" if there are different values for the start and end shapes.
    }
});

Note: type:"rotational" was added in version 0.9.0 (released with GSAP 2.1).

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 <rect> Like this:
<rect id="endShape" width="100" height="100" fill="red"/>
//becomes
<path id="endShape" fill="red" d="M100,0 v100 h-100 v-100 h100z"></path>

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 precompile 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

• SVG Pencil Download by Chris Gannon
• "!?" to GreenSock Logo by Chris Gannon
• Send Email Success/Failure by Chris Gannon
• Father & Son by Diaco
• Count Down & Count Up by Chris Gannon
• Life is Short by Chris Gannon
• Bow & Arrow by Chris Gannon
• Simple Polyline Morphing by Jack
• Happy/Sad Face (click the face) by Chris Gannon
• Bad Hair Day (click the face) by Chris Gannon
• Floating Duckie by Brad Larson
• Power of GSAP (lightening) by Diaco
• Animal Shapes by Carl Schooff

Rendering to canvas

SVG is fantastic, but sometimes developers have a canvas-based project (often for rendering performance reasons). As of version 0.9.0, MorphSVG plugin allows you to define a render function that'll be called every time the path updates, and it will receive two parameters:

1. rawPath [array]: A RawPath is essentially an array containing an array for each contiguous segment with alternating x, y, x, y cubic bezier data. It's like an SVG <path> where there's one segment (array) for each "M" command; that segment (array) contains all of the cubic bezier coordinates in alternating x/y format (just like SVG path data) in raw numeric form which is nice because that way you don't have to parse a long string and convert things. For example, this SVG <path> has two separate segments because there are two "M" commands: [raw][code] [/code][/raw] So the resulting RawPath would be:

   [
     [0, 0, 10, 20, 15, 30, 5, 18],
     [0, 100, 50, 120, 80, 110, 100, 100]
   ]

   For simplicity, the example above only has one cubic bezier in each segment, but there could be an unlimited quantity inside each segment. No matter what path commands are in the original <path> data string (cubic, quadratic, arc, lines, whatever), the resulting RawPath will ALWAYS be cubic beziers.
2. target [object]: the target of the tween (usually a <path>)

Demo: MorphSVG canvas rendering

Here's an example of a tween and a render function that'd draw the morphing shape to canvas:

var canvas  = document.querySelector("canvas"),
	ctx = canvas.getContext("2d"),
	vw = canvas.width  = window.innerWidth,
	vh = canvas.height = window.innerHeight;

ctx.fillStyle = "#ccc";

TweenMax.to("#hippo", 2, {
	morphSVG:{
		shape:"#circle", 
		render:draw
	}
});

function draw(rawPath, target) {  
  var l, segment, j, i;
  ctx.clearRect(0, 0, vw, vh);
  ctx.beginPath();
  for (j = 0; j < rawPath.length; j++) {
    segment = rawPath[j];
    l = segment.length;
    ctx.moveTo(segment[0], segment[1]);
    for (i = 2; i < l; i+=6) {
      ctx.bezierCurveTo(segment[i], segment[i+1], segment[i+2], segment[i+3], segment[i+4], segment[i+5]);
    }
    if (segment.closed) {
      ctx.closePath();
    }
  }
  ctx.fill("evenodd");
}

To set a default render method for all tweens:

MorphSVGPlugin.defaultRender = yourFunction;

updateTarget:false

By default, MorphSVG will update the original target of the tween (typically an SVG <path> element), but if you're only drawing to canvas you can tell MorphSVG to skip updating the target like this:

TweenMax.to("#hippo", 2, {
	morphSVG:{
		shape:"#circle", 
		render:draw,
		updateTarget:false
	}
});

To set the default updateTarget value for all tweens (so that you don't have to add it to every tween):

MorphSVGPlugin.defaultUpdateTarget = false;

Advanced features explained

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.