MorphSVGPlugin Performance Update

December 22nd 2015 | Carl


Since launching MorphSVGPlugin, we've made a bunch of improvements and exposed several new features. Here are the highlights...

The challenge

Before we dive into solutions, it helps to understand the tasks that MorphSVGPlugin must perform in order to work its magic:

  • Convert the path data string into pure cubic Beziers
  • Map all of the segments between the start and end shapes (match them up), typically based on size and position
  • If there are more segments in one than the other, fabricate new segments and place them appropriately
  • Subdivide any segments with mis-matching point quantities
  • If a shapeIndex number isn't defined, locate the one that delivers the smoothest interpolation (shortest overall distance that points must travel). This involves looping through all the anchor points and comparing distances.
  • Convert all the data back into a string
  • Isolate the points that need to animate/change and organize a data structure to optimize processing during the tween.

That may sound like a lot of work (and it is) but MorphSVGPlugin usually rips through it with blazing speed. However, if you've got a particularly complex path, you'll appreciate the recent improvements and the new advanced options:

Performance tip #1: define a shapeIndex

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:"#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..."#id", 1, {morphSVG:{shape:"#otherID", shapeIndex:[3]}});


  • shapeIndex:"log" was added in MorphSVGPlugin version 0.8.1.
  • A single segment value can be defined as a number or a single-element array, like shapeIndex:3 or shapeIndex:[3] (both produce identical results)
  • Any segments that don't have a shapeIndex defined will always use "auto" by default. For example, if you morph a 5-segment path and use shapeIndex:2, it will use 2 for the first segment and "auto" for the other four.

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:"#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..."#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: 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: You may noticed that it starts more smoothly.


  • precompile was added in MorphSVGPlugin version 0.8.1.
  • 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.

Better 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)."#id", 1, {morphSVG:{shape:"#otherID", map:"complexity"}});


  • 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


See the Pen pathDataToBezier() docs official by GreenSock (@GreenSock) on CodePen.

Morph back to the original shape anytime

If you morph a path into various other shapes, and then you want to morph it back to its original shape, it required saving the original path data as a variable and feeding it back in later. Not anymore. MorphSVGPlugin records the original path data in a "data-original" attribute directly on the element itself, and then if you use that element as the "shape" target, it will automatically grab the data from there. For example:"#circle", 1, {morphSVG:"#hippo"}); //morphs to hippo"#circle", 1, {morphSVG:"#camel"}); //morphs to camel"#circle", 1, {morphSVG:"#circle"}); //morphs back to circle.


We continue to be amazed by the response to MorphSVGPlugin and the creative ways we see people using it. Hopefully these new features make it even more useful.

How do I get MorphSVGPlugin? If you're a "Shockingly Green" or "Business Green" Club GreenSock member, just download the zip from your account dashboard or the download overlay on GSAP-related page on this site. If you haven't signed up for Club GreenSock yet, treat yourself today.


Version: 1.19.0 updated 2017-01-17




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

        Help support GreenSock by becoming a member

        Join Club GreenSock