MotionPathHelper
Quick Start
Trial URL
MotionPathHelper is a Club GSAP perk, join today or grab this trial URL to take it for a spin for free. Works on localhost, Codepen, CodeSandbox and Stackblitz.
gsap.registerPlugin(MotionPathHelper)
Minimal usage
MotionPathHelper.create(tween);
MotionPathHelper is a Club GSAP perk that lets you interactively edit a motion path directly in the browser by dragging its anchors and control points, adding/deleting them, or dragging the entire path! If you don't have a motion path yet, you can create a new one from scratch. Once you're done editing, simply click the big "COPY MOTION PATH" button at the bottom of the screen to have the path data string copied to your clipboard so that you can then paste it directly into your tween or an SVG <path>
that you'll use for the motion path animation.
Without MotionPathHelper, you'd need to go back and forth between the browser and an SVG editor like Inkscape or Adobe Illustrator which is time-consuming and frustrating.
Video
The video below explains MotionPathPlugin, and shows MotionPathHelper around 3:18:
Usage
Call MotionPathHelper.create()
and pass it either of the following:
A Tween instance that has a motionPath defined. In this case, it will grab the motion path from the Tween and make it editable in the browser. For example:
const tween = gsap.to("#id", {
motionPath: {
path: "#path",
align: "#path",
alignOrigin: [0.5, 0.5],
},
});
// pass the tween instance in here...
MotionPathHelper.create(tween);An element (or selector text). In this case, it will create a new very basic motion path curve that you can start editing. For example:
// just pass the element or selector text:
MotionPathHelper.create("#id");
Configuration
You can optionally pass in a vars
parameter to further configure the motion path helper. It's an object and can include any of the following properties:
- Number - The ease to use for the looping preview animation.
- Number - The duration of the looping preview animation (each iteration)
String | Element | Array The motion path along which to animate the target(s). This can be a direct reference to a
or selector text or path data like "M9,100c0,0,18-41,49-65" or an Array of points through which the path should be plotted. - String - The color of the path stroke (only applies if no
path
is defined and MotionPathHelper must create one). - Number - The stroke-width of the path (only applies if no
path
is defined and MotionPathHelper must create one). - Number - The opacity of the path stroke (only applies if no
path
is defined and MotionPathHelper must create one). - Boolean - Whether or not the path will be selected initially.
- Number - The position along the path at which to start, where 0 is the beginning and 1 is the end and 0.5 is the middle. 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. This only applies if there is no existing animation that the MotionPathHelper is showing. - Number - The position along the path at which to end, where 0 is the beginning, 1 is the end, and 0.5 is in the middle. It can be any positive or negative decimal number, including a value that's less than the start (which would make the object travel backwards). For example,
0.6
would have the element end at the 60% point along the curve. 1.5 would make it loop around back to the beginning and stop at the halfway point. Default is 1. This only applies if there is no existing animation that the MotionPathHelper is showing.
Property
Description
Sample code
MotionPathHelper.create("#elementID", {
path: "#path",
pathWidth: 5,
pathColor: "red",
pathOpacity: 0.6,
selected: true,
start: 0.1,
end: 1,
duration: 5,
ease: "power2.inOut",
});
Demo
loading...
Editing tips
- Add point: ALT-Click somewhere on the path
- Toggle smooth/corner anchor: ALT-Click the anchor
- Get handle from corner anchor: ALT-Drag
- Select multiple anchors: SHIFT-Click (and again to deselect)
- Delete anchor: select it, then press DELETE key.
- Undo: CTRL-Z
- Click and drag on handles to change how the path curves.
- Drag entire path: Click and drag on a part of the path that doesn't have an anchor
MotionPathHelper requires MotionPathPlugin. Don't forget to load and register both plugins. :::
:::
Methods
kill( ) ; | Kills the MotionPathHelper instance, removing the path editing elements and "Copy" button from the DOM. |
MotionPathHelper.editPath( path:Element | String, config:Object ) : PathEditor | Makes an SVG |
FAQs
How do I include MotionPathPlugin in my project?
See the installation page for all the options (CDN, NPM, download, etc.) where there's even an interactive helper that provides the necessary code. Easy peasy. Don't forget to register MotionPathPlugin like this in your project:
gsap.registerPlugin(MotionPathPlugin, MotionPathHelper)
Is this included in the GSAP core?
Is this only for Club GSAP members?
Yes. It's our way of saying "Thank you" to those who support our efforts. If you're not a member, what are you waiting for? Satisfaction is guaranteed or your money back. Take your animation skills to the next level. If you're already a member, you can download GSAP along with this and the other bonus plugins from your account dashboard. See the installation page for details about how to get it into your project via a <script>
tag or NPM, Yarn, etc.
Can I try MotionPathPlugin out for free?
You betcha! There's a trial (but fully-functional) version of MotionPathPlugin that you can use on Codepen as much as you want for free. Get the URLs here. It's a fantastic way to experiment. Note: the trial version of the plugins will only work on the CodePen domain.
It works fine during development, but suddenly stops working in the production build! What do I do?
Your build tool is probably dropping the plugin when tree shaking and you forgot to register MotionPathPlugin, MotionPathHelper (which protects it from tree shaking). Just register the plugin like this:
gsap.registerPlugin(MotionPathPlugin, MotionPathHelper)