| name | astro-gsap-scrolltrigger |
| description | Use when adding, fixing, or reviewing GSAP ScrollTrigger behavior in Astro pages, especially with view transitions, static routes, client scripts, reduced motion, cleanup, or browser-only lifecycle constraints. |
| cluster | creative-frontend |
| version | 1.0.0 |
Astro GSAP ScrollTrigger
Purpose
Use GSAP in Astro without breaking static rendering, route transitions, accessibility, or mobile performance.
Required Pattern
- Keep all
window, document, matchMedia, gsap, and ScrollTrigger initialization inside client-side <script> blocks or imported browser scripts.
- Never access browser APIs in Astro frontmatter; frontmatter runs on the server/build side.
- Register
ScrollTrigger once in the browser script.
- Initialize on
astro:page-load.
- Cleanup on
astro:before-swap.
- Respect
prefers-reduced-motion: reduce.
- Animate only
transform and opacity unless there is a measured reason.
- Call
ScrollTrigger.refresh() after layout-affecting images/content are ready.
Minimal Lifecycle Shape