Use CSS for simple state changes—hover, focus, toggles, short fades—and GSAP when you need timelines, sequencing, scroll-linked motion, or coordination across many elements. Neither library replaces the other; strong production builds mix both on purpose. This decision matrix shows when to reach for each tool and how we structure the hybrid pattern on client work through motion web development engagements.
The wrong choice rarely breaks a demo. It shows up later as janky scroll sections, styles that are impossible to override, or animation code nobody can safely edit three sprints after launch.
What CSS animations do well
CSS transitions and keyframe animations live in the style layer. They are ideal for microinteractions tied to a single state change: button hover, accordion open, focus ring, menu underline, skeleton swap. Because the browser understands these as style updates, implementation stays declarative—you change a class or property and the transition runs. That keeps component code small and makes reduced-motion overrides straightforward.
CSS also wins on cost of entry. No bundle dependency, no init call, no ordering bugs between scripts. For a marketing site whose motion plan is polish without scroll storytelling, pure CSS is often the entire toolkit. The heuristic we apply in estimates: if the motion is a state, prefer CSS; if it is a narrative or sequence, look harder at GSAP.
Where CSS struggles: orchestrating many elements over time, scrubbing progress against scroll position, pausing and reversing complex sequences, or coordinating a timeline with route changes. You can force those in CSS, but you end up maintaining brittle keyframe stacks and JavaScript that fights the cascade.
What GSAP does well
GSAP is a JavaScript animation engine built for timelines. Its sweet spots are entrance sequences with stagger, scroll-driven scenes, SVG draw effects, and any sequence that must play, pause, reverse, or be controlled by scroll position. Timelines give you a single source of truth for order and duration, which matters when a hero animation coordinates headline, image, and CTA.
Scroll-linked motion is the clearest divider. CSS has scroll-driven animation support in some engines, but production agency work usually needs wider control: pin a section, map progress to multiple properties, sync a progress bar, and degrade cleanly when motion is reduced. That control set is where GSAP (and its ScrollTrigger workflow) remains the default tool we specify in GSAP motion systems in production.
The tradeoff is weight and ownership. Every GSAP feature you use is more JavaScript on the critical path and more code your next developer must understand. Motion that could be a two-line transition does not justify a timeline. Teams also forget accessibility: whatever GSAP runs must still respect prefers-reduced-motion, which means your JS layer needs the same media query discipline as your CSS.
Decision matrix
| Scenario | Prefer CSS | Prefer GSAP | Why |
|---|---|---|---|
| Button hover / focus states | Yes | — | Single property change; CSS transition is enough and stays declarative |
| Accordion / tab open-close | Yes (short) | If multi-element | CSS handles height/opacity; GSAP if several parts must sequence |
| Hero entrance on load | Simple fade | Staggered sequence | One-shot fade suits CSS; choreographed stagger across elements suits timelines |
| Scroll storytelling / pinned scenes | Rarely | Yes | Progress control, pinning, and multi-property sync need a JS timeline |
| Page / route transitions | Out-in CSS | Orchestrated exit + enter | Simple crossfades are CSS; coordinated exit → swap → enter needs sequencing—and an INP budget (see transitions vs INP) |
| Loading microinteractions | Yes | If data-driven | CSS spinners and pulses; GSAP if progress maps to real timeline events |
| SVG path drawing / complex morphs | Limited | Yes | Path control and draw effects are clearer in a JS engine |
| Reduced-motion fallback | Media query in CSS | Must branch in JS | CSS can disable in one block; GSAP needs an explicit matchMedia check |
The hybrid pattern we ship
In practice we split by layer. CSS owns anything state-driven inside components: colors, transforms on hover, focus visibility, skeleton fades, and the global reduced-motion kill switch. GSAP owns section-level choreography and scroll scenes—hero timelines, feature reveals, pinned product tours—initialized once per page behind feature checks.
Three rules keep the hybrid stable. One owner per element: if GSAP animates a headline on load, CSS does not also transition that entrance. GSAP scenes stay additive to a readable static state so the page works if the script fails. Every GSAP scene registers a reduced-motion branch that skips or collapses duration, mirroring the CSS override.
Route transitions need the most discipline. If you orchestrate exit and enter in JavaScript, keep input responsive—long main-thread sequences push INP toward the 200ms threshold. Budget the sequence, preload what you need, and keep click-to-next-paint short; details live in page transitions without killing INP. For a reference build that balances spectacle and restraint, Switch Sound & Music shows motion that supports the brand without turning the page into a demo reel.
Examples in plain terms
Transitions: A pill CTA that scales on hover is CSS—two properties, one transition, zero JS. A preloader that counts up, swaps a logo mark, then reveals a staggered hero is a GSAP timeline with a reduced-motion path that jumps straight to the revealed state.
Scroll: A section that fades in on viewport entry can be CSS with an intersection class. A section that pins while an inner diagram builds as you scroll needs scroll-linked progress—GSAP territory. Mixing both across one page is normal; mixing both on the same element is how you get flicker.
Microinteractions: Toggles, tooltips, nav underlines, and card lift stay in CSS unless the interaction must sync with audio, data, or a multi-step coach mark. Try CSS first and promote to GSAP only when you hit a real orchestration wall.
Key takeaways
- Default to CSS for state changes; promote to GSAP for timelines, scroll progress, and multi-element sequences. The matrix above is the tie-breaker we use in scoping.
- Hybrid builds work when ownership is split by layer, static content remains readable without JS, and both CSS and GSAP honor reduced-motion. Check transition patterns against INP before shipping anything route-level.
FAQ
Is GSAP always better than CSS animations?
No. GSAP adds capability and cost. For hover states, short fades, and simple toggles, CSS is lighter, easier to maintain, and simpler to disable for reduced motion. Reserve GSAP for sequences and scroll scenes that CSS would force you to hack.
Can we use CSS scroll-driven animations instead of GSAP?
For simple progress-linked effects where browser support matches your audience, CSS scroll-driven animations can work. Agency builds that need pinning, multi-property scrubbing, or predictable fallbacks still tend to favor a JS timeline. Decide from the interaction brief, not from novelty.
How do we keep GSAP from hurting Core Web Vitals?
Animate transform and opacity where possible, keep timelines off the critical first-input path, avoid layout-thrashing properties on scroll, and do not let transition sequences block clicks. Interaction latency should stay under the 200ms INP threshold; see the transitions guide for concrete patterns.
Does GSAP support prefers-reduced-motion?
Yes—you implement it. Check matchMedia('(prefers-reduced-motion: reduce)') before creating scenes (or use GSAP’s matchMedia API) and skip or collapse durations accordingly. Mirror the same rules in your CSS so static overrides still apply when JS is late or absent.
Who owns motion in a white-label build?
Whoever implements the system should own the motion code paths, but the intent has to arrive in the handoff. That means motion notes with trigger, duration, easing, and reduced-motion behavior—covered in the Figma handoff checklist—so design, your agency, and the delivery partner are not improvising separately.