Install GSAP via NPM:
npm install gsap
As of GSAP 2.0, ES modules are used by default (CommonJS/UMD are still available; scroll down for more info). You can import individual classes like:
import TweenMax from "gsap/TweenMax"; import Draggable from "gsap/Draggable";
TweenMax includes (and exports) many of the commonly-used classes so you can also do this:
import { TweenMax, TimelineLite, Power2, Elastic, CSSPlugin } from "gsap/TweenMax";
(TweenMax includes TweenLite, TimelineLite, TimelineMax, CSSPlugin, RoundPropsPlugin, BezierPlugin, DirectionalRotationPlugin, AttrPlugin, and all eases except CustomEase, CustomWiggle, and CustomBounce)
As a convenience, there's also an "all" file that imports/exports every GSAP tool (except members-only bonus plugins), so you can do this:import { TimelineMax, CSSPlugin, ScrollToPlugin, Draggable } from "gsap/all";IMPORTANT: if your animations aren't working as expected, it's likely an issue with tree shaking (see below) which can be easily resolved by referencing any plugins you're using.
Tree shaking
Some bundlers like Webpack offer a convenient feature called "tree shaking" that attempts to identify modules that you're not referencing anywhere in your code, and drops them from the bundle to reduce file size. Sounds great, but GSAP plugins (like CSSPlugin) aren't typically referenced anywhere directly by users, so they're ripe for getting accidentally plucked by tree shaking. That can break your animations. The solution? Simply reference the plugin somewhere in your code, like:
import { TimelineLite, CSSPlugin, AttrPlugin } from "gsap/all"; //without this line, CSSPlugin and AttrPlugin may get dropped by your bundler... const plugins = [ CSSPlugin, AttrPlugin ]; var tl = new TimelineLite(); tl.to(".myClass", 1, {x:100, attr:{width:300}});Note: To maximize backward compatibility and avoid tree shaking issues, the main TweenMax file automatically activates all the classes that were historically bundled with it (like CSSPlugin, BezierPlugin, AttrPlugin, etc.). That affects bundle size accordingly, of course. If you prefer to ONLY pull in the base TweenMax class (without auto-activating the others), you can use the
TweenMaxBase
file (as of 2.0.0), like:
//skips auto-activing the other plugins/classes import { TweenMax } from "gsap/TweenMaxBase";
To get tree shaking to work in Webpack, you may need to set {modules:false}
in your babel config file. Here are some links that may be useful:
- https://webpack.js.org/guides/tree-shaking/
- https://webpack.js.org/loaders/babel-loader/
- https://rollupjs.org/guide/en#danger-zone
UMD/CommonJS
If your environment doesn't accommodate ES modules yet, don't worry - we've got you covered. There's a "umd" directory that contains...you guessed it...regular old ES5 UMD (Universal Module Definition) versions of the files which are compatible with pretty much everything (RequireJS, Browserify, etc.). So you could import them like:
//get the UMD versions. Notice the "/umd/" in the path... import { TweenMax, Power2, TimelineLite } from "gsap/umd/TweenMax"; import ScrollToPlugin from "gsap/umd/ScrollToPlugin"; import Draggable from "gsap/umd/Draggable";
What about bonus plugins like MorphSVGPlugin?
Obviously we can't distribute the members-only bonus plugins via NPM, so all you need to do is log into your GreenSock account and download the latest zip which will contain a "bonus-files-for-npm-users" folder that has just the bonus plugins/tools. Then you can just plop that into your project, like maybe in your /src/ folder (or wherever) and import them directly. For example, to save some typing you could rename the "bonus-files-for-npm-users" to simply "gsap-bonus" and put that in the root of your project and then:import MorphSVGPlugin from "./gsap-bonus/MorphSVGPlugin"; import SplitText from "./gsap-bonus/SplitText";You could certainly drop the bonus files into the /node_modules/gsap/ folder if you prefer, but most people don't like doing that because it makes things less portable/updatable.
If you're not a Club GreenSock member yet, check it out!
CDN: still a great option
You certainly don't NEED to use GSAP via NPM or a build system - you can simply load the JS file(s) from the CDN in<script>
tags like:<script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/2.1.3/TweenMax.min.js"></script>That way, you'll get the benefit of the ubiquitous caching. Over 4,000,000 sites use GSAP, so tapping the CDN can improve speed.
Why can't I just import any class from "gsap"?
Because historically "gsap" pointed to TweenMax (before we moved to ES modules) and we didn't want to break existing projects or suddenly cause them to get much bigger in build systems that didn't leverage tree shaking. We take backward compatibility very seriously. But when we move to version 3.0.0, our goal is to clean things up a bit.Typescript
We don't have any official TypeScript definition files (sorry), but there are two that might fit your needs: @types/greensock or @types/gsap. Please contact the authors of those repos if you encounter any problems. Also, in some environments (ones that aren't friendly to ES modules) it's best to import the UMD files in a slightly different way, like:import * as Draggable from "gsap/umd/Draggable"; import * as TweenMax from "gsap/umd/TweenMax";