Get GSAP

Version: 1.19.0 updated 2016-07-18

Core

    Extras

      Plugins

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

        Learn more about MorphSVGPlugin.

        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.

        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"});

        See the Pen MorphSVG : Docs Basic Usage by GreenSock (@GreenSock) on CodePen.

        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.

        And 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 and elephant.

        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");

        See the Pen MorphSVG - sequence by GreenSock (@GreenSock) on CodePen.

        Note: MorphSVGPlugin requires GSAP 1.18.0 (TweenLite or TweenMax)

        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.

        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");

        See the Pen findShapeIndex() Docs by GreenSock (@GreenSock) on CodePen.

        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).

        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>

        MorphSVGPlugin Examples

        Get your hands on MorphSVGPlugin

        MorphSVGPlugin is a bonus plugin for Club GreenSock members ("Shockingly Green" and "Business Green" levels). It's our way of showing our gratitude to those who 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.

        For an all-access pass to premium content

        Join Club GreenSock