GSAP Intro
CSS transitions and keyframe animations handle most UI motion well. Where they start to struggle is sequencing: animating a series of elements in a specific order with precise timing relationships between them. Doing that in CSS requires carefully calculated delays, and changing the order or timing of any step means recalculating every delay that follows. GSAP (GreenSock Animation Platform) solves this with a timeline model where you define what each element does and how it relates to the previous step, and GSAP handles all the math.
GSAP is a JavaScript library, not a CSS tool. It manipulates properties directly on DOM elements and runs its own animation engine, which is consistently smooth across browsers and significantly faster than JavaScript-based alternatives. It also ships a ScrollTrigger plugin that handles scroll-linked animation with far more control than CSS scroll-driven animations currently offer. This page covers loading GSAP, writing tweens and timelines, and using ScrollTrigger for scroll-based effects.
Loading GSAP via CDN
For your portfolio, the easiest path is a CDN with plain <script src="..."> tags in index.html. No npm install and no build step. Load the core library first, then any plugins you need, then your own script file. Use the GSAP install helper to generate current CDN URLs and pick the plugins your demo needs.
Open the GSAP install helper, choose CDN and UMD / script tag (skip ESM unless you already use a bundler). Check ScrollTrigger, copy the generated <script> lines into your index.html before your own animation.js. In your script file, register plugins with gsap.registerPlugin(ScrollTrigger) before any animation code.
<!-- Core GSAP library -->
<script src="https://cdn.jsdelivr.net/npm/gsap@3.15/dist/gsap.min.js"></script>
<!-- ScrollTrigger plugin (load after core) -->
<script src="https://cdn.jsdelivr.net/npm/gsap@3.15/dist/ScrollTrigger.min.js"></script>
<!-- Your script (load last) -->
<script src="animation.js"></script>
This example matches GSAP 3.15 on jsDelivr. If GreenSock updates paths, use the install helper instead of memorizing URLs.
In your script file, register ScrollTrigger before writing any animation that uses it. This step is required: GSAP's plugin architecture is tree-shaking-safe by default, which means plugins are excluded unless explicitly registered.
// Register plugins before any animation code
gsap.registerPlugin(ScrollTrigger);
The most important habit when learning GSAP is to configure before you code. Before writing a single tween, decide what elements animate, in what order, and with what timing relationships. Sketch it out or describe it in comments. GSAP timelines make it easy to change timing later, but starting with a clear picture prevents the "add another delay and hope" approach that makes CSS animation sequences hard to maintain.
Tweens: The Basic Unit
A tween is a single animation that moves a property from one value to another. GSAP provides three tween methods that cover all cases:
-
gsap.to(target, vars): Animates from the element's current state to the values you specify. The most common form. -
gsap.from(target, vars): Animates from the values you specify to the element's current state. Useful for entrance animations where the element starts invisible or offset. -
gsap.fromTo(target, fromVars, toVars): Explicitly sets both the start and end values. Use this when you need full control over both states, especially inside a timeline where the element's current state may be ambiguous.
// Move a box 200px to the right over 1 second
gsap.to('.box', { x: 200, duration: 1 });
// Fade in from invisible
gsap.from('.hero-title', { opacity: 0, y: 30, duration: 0.6, ease: 'power2.out' });
// Explicit start and end
gsap.fromTo('.badge',
{ scale: 0.8, opacity: 0 },
{ scale: 1, opacity: 1, duration: 0.4, ease: 'back.out(1.7)' }
);
GSAP property names use camelCase and map closely to CSS: x maps to translateX, y to translateY, scale to scale, rotation to rotate. GSAP automatically uses transform under the hood for these, so they are compositor-friendly by default. You can also pass full CSS property names as strings for properties that do not have GSAP shorthands.
Easing in GSAP
GSAP has its own easing syntax that is more expressive than CSS timing functions. Named eases follow the pattern family.direction, such as power2.out, elastic.inOut, or back.out(1.7). The number in parentheses on configurable eases is an intensity parameter. back.out(1.7) produces a slight overshoot on exit; increasing the number increases the overshoot.
gsap.to('.card', { y: -12, ease: 'power2.out', duration: 0.3 }); // smooth deceleration
gsap.to('.modal', { scale: 1, ease: 'back.out(1.4)', duration: 0.4 }); // slight spring
gsap.to('.loader', { rotation: 360, ease: 'none', repeat: -1, duration: 1 }); // linear spin
Timelines
A timeline is a container for multiple tweens that play in sequence. The key advantage over individual tweens with delays is that changing one step's duration does not require recalculating everything that follows. Each tween in a timeline automatically starts when the previous one ends, unless you use the position parameter to adjust that.
// Create a timeline
const tl = gsap.timeline();
// Each tween starts after the previous one finishes
tl.from('.hero-title', { opacity: 0, y: 40, duration: 0.6, ease: 'power2.out' })
.from('.hero-subtitle',{ opacity: 0, y: 20, duration: 0.4, ease: 'power2.out' })
.from('.hero-cta', { opacity: 0, y: 20, duration: 0.3, ease: 'power2.out' });
The Position Parameter
Every timeline method accepts an optional position parameter as the last argument that controls when that tween starts relative to the timeline. Without it, tweens chain sequentially. With it, you can overlap, offset, or anchor tweens to absolute times.
const tl = gsap.timeline();
tl.from('.panel-1', { opacity: 0, x: -60, duration: 0.5 })
// "+=0.2" means 0.2s after the previous tween ends
.from('.panel-2', { opacity: 0, x: -60, duration: 0.5 }, '+=0.2')
// "-=0.3" means 0.3s before the previous tween ends (overlap)
.from('.panel-3', { opacity: 0, x: -60, duration: 0.5 }, '-=0.3')
// "<" means start at the same time as the previous tween
.from('.panel-label', { opacity: 0, duration: 0.3 }, '<')
// absolute position: start at exactly 1 second into the timeline
.from('.badge', { scale: 0, duration: 0.3, ease: 'back.out' }, 1);
Pass a defaults object when creating a timeline to apply shared properties to every tween in it. This keeps your tween calls lean and makes global changes (like adjusting the easing across the whole sequence) a one-line edit.
const tl = gsap.timeline({
defaults: { duration: 0.5, ease: 'power2.out' }
});
// Duration and ease are inherited; only unique values need to be specified
tl.from('.title', { opacity: 0, y: 30 })
.from('.subtitle', { opacity: 0, y: 20 })
.from('.cta', { opacity: 0, scale: 0.9 });
Timeline Demo
This course page loads GSAP in the background for the demo only. On your portfolio, use the script tags from the CDN section above.
The demo below plays a three-panel entrance sequence using a GSAP timeline with the position parameter to create overlapping motion. Use the replay button to watch it again. The slow-motion toggle stretches the timeline so the sequencing and overlaps are easier to see.
ScrollTrigger
ScrollTrigger is a GSAP plugin that links any tween or timeline to scroll position. At its simplest, it fires an animation when an element enters the viewport. At its most powerful, it scrubs a full timeline forward and backward in sync with the scroll position.
gsap.registerPlugin(ScrollTrigger);
// Animate when .section enters the viewport
gsap.from('.section', {
opacity: 0,
y: 50,
duration: 0.8,
ease: 'power2.out',
scrollTrigger: {
trigger: '.section', // element that triggers the animation
start: 'top 80%', // when top of trigger hits 80% down the viewport
end: 'bottom 20%', // when bottom of trigger hits 20% down the viewport
toggleActions: 'play none none reverse'
}
});
Key ScrollTrigger Properties
-
trigger: The element whose position controls when the animation fires. Can be a selector string or a DOM element. -
startandend: Each takes two values separated by a space: a position on the trigger element and a position on the viewport.'top 80%'means "when the top of the trigger reaches 80% down the viewport." -
toggleActions: Four values describing what happens on enter, leave, re-enter, and re-leave:'play pause resume reverse'is a common pattern. Use'play none none none'for a one-time entrance that does not reverse on scroll back. -
scrub: When set totrueor a number, the animation's progress is tied directly to the scroll position rather than playing independently. A number value adds smoothing:scrub: 1means the animation catches up to the scroll position over 1 second. -
markers: Set totrueduring development to draw visible lines for the start and end positions. Always remove before shipping.
// Scrubbed timeline: progress tied to scroll position
const tl = gsap.timeline({
scrollTrigger: {
trigger: '.scroll-section',
start: 'top top',
end: '+=600', // pin for 600px of scrolling
scrub: 1,
pin: true, // pin the section while scrubbing
markers: true // remove before shipping
}
});
tl.from('.step-1', { opacity: 0, x: -100 })
.from('.step-2', { opacity: 0, x: -100 }, '+=0.2')
.from('.step-3', { opacity: 0, x: -100 }, '+=0.2');
CSS Scroll-Driven vs. GSAP ScrollTrigger
Both tools animate elements based on scroll position. Choosing between them depends on what your animation needs to do.
-
Use CSS scroll-driven animations when the effect is simple (a fade-in, a progress bar, a parallax shift), you want zero JavaScript, and the 83% browser support is acceptable. The
no-preferencecontainment pattern handles Firefox and reduced-motion in one block. -
Use GSAP ScrollTrigger when you need pinned sections, precise sequencing across multiple elements, scrub smoothing, or the animation is complex enough that the CSS approach would require deeply nested
animation-rangemath. ScrollTrigger also gives you callbacks (onEnter,onLeave, etc.) that CSS cannot match. - Do not use GSAP just because the effect looks cool in a demo. Loading an external library for a single fade-in that CSS handles in three lines is not a good trade. GSAP earns its place when the sequencing or interactivity genuinely cannot be done cleanly in CSS.
Reduced Motion with GSAP
GSAP provides gsap.matchMedia() as the idiomatic way to respect prefers-reduced-motion. It accepts a configuration object where keys are media query strings and values are setup functions. This keeps all motion-related code together and avoids scattering media query checks throughout your script.
gsap.matchMedia().add({
// Full motion for users who have not opted out
'(prefers-reduced-motion: no-preference)': () => {
gsap.from('.card', {
opacity: 0,
y: 40,
stagger: 0.1,
duration: 0.6,
ease: 'power2.out',
scrollTrigger: { trigger: '.card-grid', start: 'top 80%' }
});
},
// Reduced motion: no entrance animation, cards visible immediately
'(prefers-reduced-motion: reduce)': () => {
gsap.set('.card', { opacity: 1, y: 0 });
}
});
When using gsap.from() or gsap.fromTo(), elements start in the "from" state before the animation runs. If the animation is skipped for reduced-motion users and you have not set a fallback, those elements may be invisible or offset. Always use gsap.set() inside the reduce branch to put elements in their correct final state.
Build Your Demo
Create a new directory at unit-6/gsap/ in your portfolio with index.html and gsap.css. Load GSAP with CDN <script> tags in index.html (the simplest setup for a static GitHub Pages page). Use the GSAP install helper to copy the core and ScrollTrigger URLs.
-
Add core GSAP and ScrollTrigger
<script>tags toindex.htmlin that order, then youranimation.js(or equivalent) last. -
Call
gsap.registerPlugin(ScrollTrigger)at the top of your script file before any tweens or timelines. -
Add a link to your demo on your portfolio homepage and in your
README.md.
Your demo must also include:
- A GSAP timeline with at least three tweens that uses the position parameter to create at least one overlap or offset between steps, not just sequential chaining.
-
A ScrollTrigger that fires the timeline or a separate animation when an element enters the viewport. Include
markers: truewhile building and remove them before submitting. -
A
gsap.matchMedia()block that provides a reduced-motion alternative usinggsap.set()to put all animated elements in their final visible state. -
Only compositor-friendly properties (
x,y,opacity,scale,rotation) inside your tweens.
Teaching Video Checklist
When you record your teaching video, make sure your teammates come away understanding these concepts:
- Why a GSAP timeline is easier to maintain than individual tweens with calculated delays, and what the position parameter does to control timing relationships between tweens.
-
What
scrubdoes in ScrollTrigger and how it differs from a trigger that simply plays an animation when an element enters the viewport. - When to reach for CSS scroll-driven animations instead of GSAP ScrollTrigger, and what specifically makes GSAP worth the library cost.
-
How
gsap.matchMedia()handles reduced-motion preferences, and whygsap.set()is needed in the reduce branch when usinggsap.from(). -
Your portfolio demo: show where GSAP is loaded in
index.html(script tags from the install helper), then walk through the timeline configuration and ScrollTrigger firing on scroll. Use the slow-motion technique (pass a lowtimeScalevalue to the timeline) so teammates can see the sequencing clearly.
Start by showing the animation playing at full speed, then slow it down with tl.timeScale(0.2) in the browser console and replay it so the position parameter offsets are visible.
Resources
- GSAP Installation (CDN) — Generate script-tag URLs and pick plugins such as ScrollTrigger
- GSAP Docs: Core — Official reference for tweens, timelines, easing, and configuration
- GSAP Docs: ScrollTrigger — Full ScrollTrigger property reference with examples for scrub, pin, and callbacks
- GSAP Docs: gsap.matchMedia() — Reduced-motion and responsive animation patterns
- GSAP: Getting Started Guide — Official intro with interactive examples covering tweens and timelines