Back to Details

gsap-framer-scroll-animation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

GSAP & Framer Motion — Scroll Animations Skill

GSAP & Framer Motion — 滚动动画技能

Production-grade scroll animations with GitHub Copilot prompts, ready-to-use code recipes, and deep API references.
Design Companion: This skill provides the technical implementation for scroll-driven motion. For the creative philosophy, design principles, and premium aesthetics that should guide how and when to animate, always cross-reference the premium-frontend-ui skill. Together they form a complete approach: premium-frontend-ui decides the what and why; this skill delivers the how.
附带GitHub Copilot提示词、开箱即用的代码示例和详尽API参考的生产级滚动动画方案。
设计配套说明： 本技能提供滚动驱动动效的技术实现方案。 如需了解指导动画制作方式和适用时机的创意理念、设计原则与高端美学， 请始终搭配参考 premium-frontend-ui 技能。 二者结合可形成完整的实现方案：premium-frontend-ui 决定「做什么」和「为什么做」； 本技能提供「怎么做」的实现方法。

Quick Library Selector

快速库选择器

NeedUse
Vanilla JS, Webflow, VueGSAP
Pinning, horizontal scroll, complex timelinesGSAP
React / Next.js, declarative styleFramer Motion
whileInView entrance animationsFramer Motion
Both in same Next.js appSee notes in references
Read the relevant reference file for full recipes and Copilot prompts:
  • GSAP → 
    references/gsap.md
    — ScrollTrigger API, all recipes, React integration
  • Framer Motion → 
    references/framer.md
    — useScroll, useTransform, all recipes
需求选用库
原生JS、Webflow、VueGSAP
固定定位、横向滚动、复杂时间线GSAP
React / Next.js、声明式写法Framer Motion
whileInView入场动画Framer Motion
同一个Next.js应用中同时使用二者查看参考文档中的说明
阅读对应的参考文件获取完整示例和Copilot提示词：
  • GSAP → 
    references/gsap.md
    — ScrollTrigger API、所有示例、React集成
  • Framer Motion → 
    references/framer.md
    — useScroll、useTransform、所有示例

Setup (Always Do First)

前置配置（必须最先完成）

GSAP

GSAP

bash
npm install gsap
js
import gsap from 'gsap';
import { ScrollTrigger } from 'gsap/ScrollTrigger';
gsap.registerPlugin(ScrollTrigger); // MUST call before any ScrollTrigger usage
bash
npm install gsap
js
import gsap from 'gsap';
import { ScrollTrigger } from 'gsap/ScrollTrigger';
gsap.registerPlugin(ScrollTrigger); // MUST call before any ScrollTrigger usage

Framer Motion (Motion v12, 2025)

Framer Motion (Motion v12, 2025)

bash
npm install motion   # new package name since mid-2025
bash
npm install motion   # new package name since mid-2025

or: npm install framer-motion — still works, same API

or: npm install framer-motion — still works, same API

```js
import { motion, useScroll, useTransform, useSpring } from 'motion/react';
// legacy: import { motion } from 'framer-motion'  — also valid
```js
import { motion, useScroll, useTransform, useSpring } from 'motion/react';
// legacy: import { motion } from 'framer-motion'  — also valid

Workflow

使用流程

  1. Interpret the user's intent to identify if GSAP or Framer Motion is the best fit.
  2. Read the relevant reference document in 
    references/
    for detailed APIs and patterns.
  3. Suggest the required package installation if not already present.
  4. Implement the scaffold for the animation structure, adhering to the requested format (React components, hook requirements, or vanilla JS).
  5. Apply the correct tools (scrolling vs in-view elements) ensuring accessibility options are present and hooks don't cause infinite re-renders.
  1. 分析用户需求，判断GSAP或Framer Motion哪个更适配。
  2. 阅读
    references/
    目录下对应的参考文档，获取详细API和实现模式。
  3. 如果项目中尚未安装依赖，提示安装所需包。
  4. 按照要求的格式（React组件、Hook要求或原生JS）实现动画结构的脚手架。
  5. 选用正确的工具（滚动触发vs视图内元素触发），确保包含无障碍选项，且Hook不会导致无限重渲染。

The 5 Most Common Scroll Patterns

5种最常用滚动模式

Quick reference — full recipes with Copilot prompts are in the reference files.
快速参考 — 完整示例及Copilot提示词详见参考文件。

1. Fade-in on enter (GSAP)

1. 进入时淡入（GSAP）

js
gsap.from('.card', {
  opacity: 0, y: 50, stagger: 0.15, duration: 0.8,
  scrollTrigger: { trigger: '.card', start: 'top 85%' }
});
js
gsap.from('.card', {
  opacity: 0, y: 50, stagger: 0.15, duration: 0.8,
  scrollTrigger: { trigger: '.card', start: 'top 85%' }
});

2. Fade-in on enter (Framer Motion)

2. 进入时淡入（Framer Motion）

jsx
<motion.div
  initial={{ opacity: 0, y: 40 }}
  whileInView={{ opacity: 1, y: 0 }}
  viewport={{ once: true, margin: '-80px' }}
  transition={{ duration: 0.6 }}
/>
jsx
<motion.div
  initial={{ opacity: 0, y: 40 }}
  whileInView={{ opacity: 1, y: 0 }}
  viewport={{ once: true, margin: '-80px' }}
  transition={{ duration: 0.6 }}
/>

3. Scrub / scroll-linked (GSAP)

3. Scrub/滚动绑定动效（GSAP）

js
gsap.to('.hero-img', {
  scale: 1.3, opacity: 0, ease: 'none',
  scrollTrigger: { trigger: '.hero', start: 'top top', end: 'bottom top', scrub: true }
});
js
gsap.to('.hero-img', {
  scale: 1.3, opacity: 0, ease: 'none',
  scrollTrigger: { trigger: '.hero', start: 'top top', end: 'bottom top', scrub: true }
});

4. Scroll-linked (Framer Motion)

4. 滚动绑定动效（Framer Motion）

jsx
const { scrollYProgress } = useScroll({ target: ref, offset: ['start end', 'end start'] });
const y = useTransform(scrollYProgress, [0, 1], [0, -100]);
return <motion.div style={{ y }} />;
jsx
const { scrollYProgress } = useScroll({ target: ref, offset: ['start end', 'end start'] });
const y = useTransform(scrollYProgress, [0, 1], [0, -100]);
return <motion.div style={{ y }} />;

5. Pinned timeline (GSAP)

5. 固定时间线（GSAP）

js
const tl = gsap.timeline({
  scrollTrigger: { trigger: '.section', pin: true, scrub: 1, start: 'top top', end: '+=200%' }
});
tl.from('.title', { opacity: 0, y: 60 }).from('.img', { scale: 0.85 });
js
const tl = gsap.timeline({
  scrollTrigger: { trigger: '.section', pin: true, scrub: 1, start: 'top top', end: '+=200%' }
});
tl.from('.title', { opacity: 0, y: 60 }).from('.img', { scale: 0.85 });

Critical Rules (Apply Always)

核心规则（始终遵守）

  • GSAP: always call 
    gsap.registerPlugin(ScrollTrigger)
    before using it
  • GSAP scrub: always use 
    ease: 'none'
    — easing feels wrong when scrub is active
  • GSAP React: use 
    useGSAP
    from 
    @gsap/react
    , never plain 
    useEffect
    — it auto-cleans ScrollTriggers
  • GSAP debug: add 
    markers: true
    during development; remove before production
  • Framer: 
    useTransform
    output must go into 
    style
    prop of a 
    motion.*
    element, not a plain div
  • Framer Next.js: always add 
    'use client'
    at top of any file using motion hooks
  • Both: animate only 
    transform
    and 
    opacity
    — avoid 
    width
    , 
    height
    , 
    box-shadow
  • Accessibility: always check 
    prefers-reduced-motion
    — see each reference file for patterns
  • Premium polish: follow the premium-frontend-ui skill principles for motion timing, easing curves, and restraint — animation should enhance, never overwhelm
  • GSAP：使用前必须调用
    gsap.registerPlugin(ScrollTrigger)
  • GSAP scrub模式：始终使用
    ease: 'none'
    — scrub激活时加缓动会导致效果违和
  • GSAP React：使用
    @gsap/react
    提供的
    useGSAP
    ，不要直接用普通
    useEffect
    — 它会自动清理ScrollTrigger实例
  • GSAP调试：开发阶段添加
    markers: true
    ；生产发布前移除
  • Framer：
    useTransform
    的输出必须传入
    motion.*
    元素的
    style
    属性，不能用在普通div上
  • Framer Next.js：所有使用motion Hook的文件顶部必须添加
    'use client'
  • 二者通用：仅对
    transform
    和
    opacity
    属性做动画 — 避免动效作用于
    width
    、
    height
    、
    box-shadow
  • 无障碍：始终检查
    prefers-reduced-motion
    设置 — 实现模式参考各参考文件
  • 高端效果打磨：遵循premium-frontend-ui技能的动效时序、缓动曲线和克制原则 — 动画应该起增强作用，绝不能喧宾夺主

Copilot Prompting Tips

Copilot提示词编写技巧

  • Give Copilot the full selector, base image, and scroll range upfront — vague prompts produce vague code
  • For GSAP, always specify: selector, start/end strings, whether you want scrub or toggleActions
  • For Framer, always specify: which hook (useScroll vs whileInView), offset values, what to transform
  • Paste the exact error message when asking 
    /fix
    — Copilot fixes are dramatically better with real errors
  • Use 
    @workspace
    scope in Copilot Chat so it reads your existing component structure
  • 提前给Copilot提供完整的选择器、基础结构和滚动范围 — 模糊的提示词会产出模糊的代码
  • 针对GSAP，始终明确说明：选择器、start/end字符串、是否需要scrub或toggleActions
  • 针对Framer，始终明确说明：使用哪个Hook（useScroll还是whileInView）、偏移值、要变换的属性
  • 调用
    /fix
    时粘贴准确的错误信息 — 有真实错误时Copilot的修复效果会好很多
  • 在Copilot Chat中使用
    @workspace
    作用域，让它读取你现有的组件结构

Reference Files

参考文件

FileContents
references/gsap.md
Full ScrollTrigger API reference, 10 recipes, React (useGSAP), Lenis, matchMedia, accessibility
references/framer.md
Full useScroll / useTransform API, 8 recipes, variants, Motion v12 notes, Next.js tips
文件内容
references/gsap.md
完整ScrollTrigger API参考、10个示例、React（useGSAP）、Lenis、matchMedia、无障碍适配
references/framer.md
完整useScroll / useTransform API、8个示例、variants、Motion v12说明、Next.js使用技巧

Related Skills

关联技能

SkillRelationship
premium-frontend-uiCreative philosophy, design principles, and aesthetic guidelines — defines when and why to animate
技能关联关系
premium-frontend-ui创意理念、设计原则和美学指南 — 定义动画的适用时机和设计原因