MotionPathPlugin

Description

MotionPathPlugin allows you to easily move any SVG or DOM elements along a path created using SVG or manual points. It also allows you to create complex tweens with various easing using a single tween.

Usage

The motionPath attribute can be used in two ways:

1. It can be used as a shorthand for motionPath’s path attribute (more details below).

2. It can be used to pass an object that contains additional information including the following properties:

   • path - [required] The motion path data along which to animate an object along. Four things can be passed into the path attribute:

     1. A string selector reference to an SVG path whose data (d) you want to use. For example, path: "#path".
     2. A string that contains some SVG path data. For example, path: "M9,100c0,0,18.53-41.58,...".
     3. An array of objects to curve between. This can be used to pass objects with x and y coordinates to be used to curve an object a long a path or used to pass objects with non-coordinate data. For example, path: [{x: 100, y: 100}, {x: 300, y: 20}] or path: [{opacity: 0.3}, {opacity: 0.7}].
     4. A variable that refers to one of the three above options. For example foo where var foo = "#path";.

   • align : Selector - Aligns the object to itself ("self") or another element. For example, align: "#path" would align the object with the element with an id of "path". If you would like an object to not jump to its start, you might want to use immediateRender: true passed into the vars object.

   • autoRotate : [Number | Boolean] - Rotates the element along the path it is in motion on. true aligns the top left corner of the element along the path. If a number is given instead, it will be rotated by that many degrees instead. For example, autoRotate: 90 would rotate the element by 90 degrees and move it along the path, auto-rotating it to keep it at that angle along the curve. If you’d like the element to rotate from its center, use the following before the motionPath tween: gsap.set(element, {xPercent: -50, yPercent: -50, transformOrigin: "50% 50%"});. Default is false.

   • start : Number - A number that defines where along the path the movement should start. It can be any positive or negative decimal number. For example, 0.3 would start the element at the 30% point along the curve. Default is 0.

   • end : Number - A number that defines where along the path the movement should end. It can be any positive or negative decimal number, including one less than the start (which would make the object go along the path backwards). For example, 0.3 would have the element end at the 30% point along the curve. Default is 1.

   • curviness : Number - A number that sets the curviness of a path generated. 1 is the default, 2 would be more curvy. Default is 1.

   • offsetX : Number - Sets the number (in pixels) that the object should be offset along the entire path in the x direction. This can be useful for alignment purposes. Default is 0.

   • offsetY : Number - Sets the number (in pixels) that the object should be offset along the entire path in the y direction. This can be useful for alignment purposes. Default is 0.

   • type : String - This property is only useful if you give MotionPathPlugin an array of values to use. There are two options for the type of a motion path in GSAP: "thru"> and "cubic". When "thru"> is used, MotionPathPlugin assumes that the points given are all anchor points and generates control points for them using a proprietary algorithm. When "cubic" is used, MotionPathPlugin assumes that the a array data is in the format of starting with the first object being an anchor, then the next two objects being 2 control points, then an anchor, 2 control points, anchor, etc. for as many iterations as you want, but obviously make sure that it starts and ends with anchors.

   • resolution : Number - This property is only useful if you give MotionPathPlugin an array of values to use. Due to the nature of bezier curves (which MotionPathPlugin uses when making a path for a set of points), plotting the progression of an object on the path over time can make it appear to speed up or slow down based on the placement of the control points and the length of each successive segment on the path. So MotionPathPlugin implements a technique that reduces or eliminates that variance, but it involves breaking the segments down into a certain number of pieces which is what resolution controls. The greater the number, the more accurate the time remapping. But there is a processing price to pay for greater precision. The default value is typically fine, but if you notice slight pace changes on the path you can increase the resolution value. Or, if you want to prioritize speed you could reduce the number. If you use a resolution value of 0, no length measurements will take place internally which delivers maximum processing speed, but you may notice changes in speed during the animation. Default is 12.

The below code would align a div to an SVG <path>. It assumes that there is a DOM element with an id of "div" and an SVG <path> with an id of "#path".

Basic demo

gsap.to("#div", {
    motionPath: {
        path: "#path",
        align: "self"
    },
    duration: 5,
    delay: 1,
    ease: "Power1.easeInOut"
});

Notes

• The path generated is NOT responsive by default due to the high amount of calculations that would have to be checked and potentially updated each tick.