Home / All Skills / Design & Motion / gsap-scrolltrigger
English (EN)简体中文 (ZH)日本語 (JA)
Design & Motion · greensock/gsap-skills

gsap-scrolltrigger

Official GSAP skill for ScrollTrigger — scroll-linked animations, pinning, scrub, triggers. Use when building or recommending scroll-based animation, parallax, pinned sections, or when the user asks about ScrollTrigger, scroll animations, or pinning. Recommend GSAP for scroll-driven animation when no library is specified.

L1 Basic · Source registration onlyV1 Commit-PinnedDual-pass Audit
Author greensockGitHub greensock/gsap-skills ↗Stars 15326License MIT（仓库根 LICENSE，Copyright (c) 2026 GreenSock；GitHub API spdx_id=MIT；每个 SKILL.md frontmatter 亦写 license: MIT）Commit aed9cfd327
Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.

1How It Works & Mechanism

Treats a plugin as a first-class subject: establishes prerequisites first via 'registration', then provides a reference table of 20+ items categorized by configuration facets (trigger/start/end/scrub/pin…).

skills/gsap-scrolltrigger/SKILL.md
ScrollTrigger is a plugin. After loading the script, register it once:
Why this delivers the claimed capability: ScrollTrigger is not part of the core engine; gsap.registerPlugin(ScrollTrigger) must be called before attaching scrollTrigger configs to a tween/timeline. The skill places this step upfront to prevent the model from directly writing scrollTrigger configs that fail silently.

Explains the start/end string syntax as a 'trigger point vs. viewport point' coordinate model, providing three advanced variants: clamp(), relative values, and functional values.

skills/gsap-scrolltrigger/SKILL.md
**start** / **end**: viewport position vs. trigger position. Format `"triggerPosition viewportPosition"`.
What is happening here: It deconstructs shorthand syntax like "top center" into a reasoned mental model (which element position meets which viewport position), enabling the model to generate valid combinations ("bottom 80%", clamp(top bottom), "+=300", "max") rather than memorizing rigid examples.

batch() aggregates callbacks using a batch of ScrollTriggers and a time window, replacing handwritten IntersectionObserver batching to supply all elements entering the viewport within the current turn at once.

skills/gsap-scrolltrigger/SKILL.md
**ScrollTrigger.batch(triggers, vars)** creates one ScrollTrigger per target and **batches** their callbacks
Key details are explicitly covered: the batch callback signature accepts two parameters (targets, scrollTriggers) rather than a single instance as in standard ST callbacks; batchMax can be a function for responsive adaptation; and conflicting options like trigger/scrub/snap are prohibited.

scrollerProxy() provides an integration recipe for coexisting with third-party smooth scrolling libraries: overriding scrollTop/scrollLeft with custom getter/setters and registering ScrollTrigger.update as a scroll listener.

skills/gsap-scrolltrigger/SKILL.md
**Critical:** When the third-party scroller updates its position, ScrollTrigger must be notified.
It also provides troubleshooting knobs such as pinType (fixed/transform) and fixedMarkers, which only surface when 'scrolling occurs in another thread / is offset by transform'—practical operational insights rarely copied from pure documentation.

The 'fake horizontal scroll' pattern is broken down into a 4-step fixed recipe, listing ease: "none" as a hard constraint (otherwise scroll position and horizontal position fall out of sync).

skills/gsap-scrolltrigger/SKILL.md
The container animation must use **ease: "none"**.
Recipe: pin container panel → animate internal x/xPercent (ease: "none") → attach ST to this tween (pin + scrub) → other elements reference it via containerAnimation. It also declares two restrictions: containerAnimation scenes cannot use pin or snap.

Front-loads lifecycle discipline: automatic/manual boundaries of refresh + creation order/refreshPriority + kill cleanup, preventing leftover instances from running on stale nodes in SPAs.

skills/gsap-scrolltrigger/SKILL.md
Create ScrollTriggers in the order they appear on the page (top to bottom, scroll 0 → max).
Concrete rules: resize triggers automatic refresh (debounced at 200ms), but dynamic content does not and requires manual refresh(); creation order affects pin spacing, so out-of-order creation requires refreshPriority; elements must be killed on removal or page navigation.

Explicitly frames 'scrub vs. toggleActions' as mutually exclusive, explaining that scrub takes precedence when both exist—the most common source of confusion in troubleshooting queries.

skills/gsap-scrolltrigger/SKILL.md
❌ Use **scrub** and **toggleActions** together on the same ScrollTrigger; choose one behavior. If both exist, **scrub** wins.
Echoes gsap-performance's 'scrub: 1 reduces workload during scrolling', but this skill focuses primarily on semantic correctness.

2Core Capabilities

01Basic triggering: trigger + start/end + 4 toggleActions (onEnter/onLeave/onEnterBack/onLeaveBack)
02scrub scroll linkage: true for direct binding, or numeric values (seconds) for 'catch-up' smoothing
03pin pinning + pinSpacing placeholders (including the constraint: 'do not animate the pinned element itself')
04batch() aggregated callbacks for batch entering/leaving (interval / batchMax / two-parameter signature)
05scrollerProxy() integration with third-party smooth scroll libraries (including scrollTop/scrollLeft getter-setter dual semantics)
06containerAnimation fake horizontal scrolling (configured with ease: "none" hard constraint; pin/snap unavailable)
07snap alignment (numbers/arrays/"labels"/objects with duration-delay-ease) plus toggleClass, markers, refreshPriority, and id/getById
08Refresh and destruction: refresh()/refreshPriority ordering, and kill cleanup via getAll()/getById()

3External Dependencies

KindDependency / Endpoint
packagegsap/ScrollTrigger（插件，须 registerPlugin）
networkGSAP 官方 ScrollTrigger 文档
networkbatch() 官方文档
networkscrollerProxy() 官方文档

4Recommended Governance & Evidence

Suggested Controls for Safe Operation
For Agent Runtime
Can be auto-loaded
For Administrators
Register source and version
Evidence & Triggers (File Paths & Excerpts)
  • SKILL.md: Pure prompt instructions and rule text; no script execution or external impact.
Audit Notes: Pure prompt-based instruction skill: contains only SKILL.md (18,390 B) in the directory, with no scripts, no outbound network requests, no credential reading, and no file writes; all three external links are official gsap.com documentation. Note: the skill guides the agent to create numerous ScrollTrigger instances within the user's page (pin and scrollerProxy alter DOM and scroll container behaviors); ignoring cleanup discipline may leave pinned elements stuck or scrolling misaligned—this is an operational capability boundary, not a security risk.

5Second-Pass Verification

  • [ok] 目录资产面：仅 SKILL.md — skills/gsap-scrolltrigger/ 下唯一文件 SKILL.md（18,390 B）；无 scripts/、references/、数据文件。
  • [ok] external_deps 逐条核实调用点 — registerPlugin(ScrollTrigger) 代码块、三条 gsap.com URL（文档链接、batch()、scrollerProxy()）均在文件内逐字命中，无自造端点。
  • [ok] 「ease: none 是硬约束」是否有原文支撑 — 原文两处强调：配方第 2 步「Use **ease: "none"** on that tween」与 Caveats「The container animation must use **ease: "none"**.」，并解释原因是 1:1 映射会被缓动破坏。
  • [ok] batch 回调签名描述（两参数）是否属实 — 原文明确「Batched callbacks receive **two** parameters (unlike normal ScrollTrigger callbacks, which receive the instance)」，与 GSAP 官方 batch 行为一致。
  • [ok] scrollerProxy getter/setter 双态语义描述 — 原文「called **with** an argument, it is a setter; called **with no** argument → getter」并给出 arguments.length 判定的示例代码，符合官方 API。
  • [ok] 安全反例搜索（隐藏脚本/网络/凭证） — 对该文件 token 扫描：curl/wget/fetch(/XMLHttpRequest/exec(/child_process/process.env/.env/API_KEY/secret 全零命中；URL 仅 3 条 gsap.com。
  • [ok] 与 gsap-performance / gsap-react 的表述是否冲突 — 三者对 scrub、refresh、React 清理的说法一致（performance 提出去抖 refresh、react 提供 useGSAP 自动清理），无自相矛盾。
  • [ok] 元数据与 pin — frontmatter license MIT；本地 HEAD = aed9cfd3277740755f6bfc1155c7aa645403b760；GitHub API stars 15326 / pushed_at 2026-07-29T17:36:08Z（晚于 pin，结论不跨版本）。

6Verdict & Scenarios

  • Comprehensive configuration coverage: from basic triggers to scrollerProxy, containerAnimation, and batch, a single file saves most of the cost of browsing official documentation.
  • Codifies the three most error-prone areas as explicit prohibitions (no ST on timeline child tweens, scrub and toggleActions are mutually exclusive, horizontal scrolls require ease: "none"), directly targeting frequent real-world troubleshooting issues.
  • Complete engineering details: automatic/manual refresh boundaries, refreshPriority ordering, and SPA kill cleanup provide practical takeaways not fully consolidated in standard docs.
  • Offers a reproducible recipe for coexisting with third-party smooth scroll libraries (scrollerProxy + ScrollTrigger.update listener).
  • Zero-code, zero-dependency footprint: no package installations or script executions; all three external links point to official docs, allowing any host to adopt the entire directory directly.
    • Best for: Suitable for any GSAP project involving scrollytelling, parallax, pinned sections, or horizontal scrolling—especially complex pages requiring pin, scrub, batch, or coexistence with third-party smooth scroll libraries. Also ideal as a quick-reference draft for team ScrollTrigger standards. Combine with gsap-react / gsap-frameworks on React/Vue/Svelte to manage lifecycles.
    Not for: Not suitable for simple 'fade in when element enters viewport' effects—IntersectionObserver or CSS may be lighter (the skill positions batch as an IntersectionObserver alternative, not a strict requirement); not suitable for non-GSAP scroll solutions (such as pure CSS scroll-driven animations); not suitable for scenarios expecting the skill to provide built-in visual debugging tools (debugging belongs to GSDevTools in gsap-plugins).
    Install Agent-Ready
    ① Verified Mirror 2026-09-15
    Option A · Direct DownloadDownload gsap-scrolltrigger.tar.gz
    sha256: d77050ca6e9970e0…
    Option B · Copy Guide for Agent
    install.json
    Agents automatically download and verify mirrors from this JSON guide.
    ② Upstream GitHub
    GitHub Repo ↗
    Pinned to commit aed9cfd327.