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

gsap-performance

Official GSAP skill for performance — prefer transforms, avoid layout thrashing, will-change, batching. Use when optimizing GSAP animations, reducing jank, or when the user asks about animation performance, FPS, or smooth 60fps.

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

Core model in one sentence: animate only compositor-friendly transform and opacity properties, avoiding layout and repaint triggers.

skills/gsap-performance/SKILL.md
keeps work on the compositor and avoids layout and most paint.
Why it delivers on claims: animations on transform/opacity can be offloaded to the compositor thread without triggering layout/reflow, whereas width/height/top/left trigger per-frame reflow. The skill translates 'performance' into actionable property selection rules rather than vague calls to 'make it fast'.

Strict usage boundaries for will-change: apply it only to elements that truly animate, never blindly.

skills/gsap-performance/SKILL.md
It hints the browser to promote the layer.
The accompanying Do Not explicitly opposes adding will-change/force3D to all elements 'just in case'—excessive layer promotion consumes VRAM and can cause even worse jank on low-end devices.

Separation of reads and writes prevents layout thrashing: when mixing GSAP with manual DOM reads/writes, complete all reads first before performing batch writes.

skills/gsap-performance/SKILL.md
Prefer doing all reads first, then all writes
What is happening here: browsers treat reading layout properties as a forced synchronous flush; alternating read-write cycles cause multiple layout recalculations per frame. The skill recommends either batching or delegating writes entirely to GSAP.

gsap.quickTo() is the right tool for high-frequency updates: reuse a single tween instead of instantiating a new one on every event.

skills/gsap-performance/SKILL.md
It reuses a single tween instead of creating new tweens on each update.
A typical scenario is mouse tracking (mousemove firing every frame): calling gsap.to() every time creates new tween objects and increases garbage collection pressure, whereas quickTo returns a reusable setter function.

Provides 'lower-cost equivalent' replacement rules for multi-element setups: use stagger instead of multiple manual delays, and use virtualization or animate only visible items for long lists.

skills/gsap-performance/SKILL.md
- Use **stagger** instead of many separate tweens with manual delays when the animation is the same;
It also advises against running hundreds of concurrent tweens and warns against creating new timelines every frame—all covered in the 'Many Elements' and 'Reduce Simultaneous Work' sections.

Dedicated performance section for ScrollTrigger: minimize pinning, use numeric scrub values, and debounce refresh calls only when layout genuinely changes.

skills/gsap-performance/SKILL.md
Call **ScrollTrigger.refresh()** only when layout actually changes (e.g. after content load), not on every resize; debounce when possible.
Complements the refresh semantics of gsap-scrolltrigger: while that skill explains 'when you must refresh', this one addresses 'avoiding overly frequent refreshes'.

Treat cleanup as a performance item: pause or kill off-screen/inactive animations to avoid constantly consuming main thread resources and memory.

skills/gsap-performance/SKILL.md
❌ Ignore cleanup; stray tweens and ScrollTriggers keep running and can hurt performance and correctness.
The same Do Not section puts 'performance' alongside 'correctness'—lingering tweens continue updating detached or removed nodes, creating both performance issues and potential bugs.

2Core Capabilities

01Property selection optimization: prioritize transform properties (x/y/scale/rotation/skew) and opacity; avoid width/height/top/left/margin/padding
02will-change layer promotion guidance (only for actively animating elements)
03Read/write batching: avoid interleaving with manual DOM operations that cause layout thrashing
04gsap.quickTo(): reuse a single tween for high-frequency property updates (e.g., mouse tracking)
05Multi-element strategies: stagger consolidation, long list virtualization, and avoiding hundreds of concurrent tweens
06ScrollTrigger tuning: prudent pinning, numeric scrub values, and debounced refresh calls
07Cleanup and load reduction: pause/kill off-screen animations, reduce concurrently animating properties

3External Dependencies

KindDependency / Endpoint
packagegsap（quickTo 属核心 API）

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 directives and rule text with no script execution or external impact
Audit Notes: Pure directive-based skill: the directory contains only SKILL.md (4,139 B) with no scripts, network calls, external links, credential reading, or file writes. It consists entirely of rendering performance trade-off recommendations (transform/opacity priority, will-change boundaries, quickTo, debounced refresh, cleanup), presenting no external attack surface. The only caveat is the applicability boundary: optimal parameters on low-end devices require empirical testing, as the skill provides directional guidance rather than rigid thresholds.

5Second-Pass Verification

  • [ok] 目录资产面：仅 SKILL.md — skills/gsap-performance/ 下唯一文件 SKILL.md（4,139 B）；无 scripts/、references/、数据文件；URL 扫描 0 条。
  • [ok] external_deps 只剩 gsap 包 — 文件内无任何 URL 或第三方工具引用，仅使用 gsap.quickTo 与 ScrollTrigger.refresh 等本体 API；包依赖证据取自 README 安装段。
  • [ok] quickTo 的描述是否与官方一致 — gsap.quickTo(target, property, vars) 返回可反复调用的函数、内部复用单个 tween，与官方 API 语义一致；示例（mousemove 中调用 xTo/yTo）即官方推荐写法。
  • [ok] 「scrub 数值可减少滚动期工作量」是否为夸大 — 原文措辞为「**scrub** with a small value (e.g. `scrub: 1`) can reduce work during scroll; test on low-end devices.」——带不确定性限定与实测建议，非断言，不构成夸大。
  • [ok] 安全反例搜索 — token 扫描：curl/wget/fetch(/XMLHttpRequest/exec(/child_process/process.env/.env/API_KEY/secret 零命中；无外部资源引用。
  • [ok] 与 gsap-scrolltrigger 的 refresh 叙述是否冲突 — scrolltrigger 要求布局变化后必须 refresh()（否则位置失准），performance 要求不要每次 resize 都 refresh 并去抖——两者互补而非矛盾（resize 本就被 ST 自动去抖处理）。
  • [ok] 元数据与 pin — frontmatter license: MIT；HEAD = aed9cfd3277740755f6bfc1155c7aa645403b760；GitHub API stars 15326 / pushed_at 2026-07-29T17:36:08Z。
  • [ok] 是否只是「常识复述」（价值质疑） — 文中给出具体替换对象（width/height/top/left → x/y/scale）、具体 API（quickTo）、具体数值建议（scrub: 1）与具体反例（just in case 加 will-change），超出泛泛常识。

6Verdict & Scenarios

  • Translates performance advice into property-level rules (providing concrete alternatives), ready for direct use in code reviews.
  • Identifies quickTo as the correct tool for high-frequency updates, steering clear of the common pitfall of instantiating tweens on every event.
  • Covers subtle hybrid scenarios like layout thrashing caused by alternating reads and writes.
  • Ties cleanup directly to both performance and correctness, curbing lingering animations left behind by a 'ship it first' mindset.
  • Extremely compact size (4,139 B) covering all core performance aspects with virtually zero loading overhead, making it ideal as an evergreen standard.
    • Best for: Ideal for the optimization phase of existing GSAP animations experiencing frame drops or jank, or as a performance checklist for new project animation guidelines; particularly valuable for mobile/low-end devices, long lists, and mouse-following interactions.
    Not for: Not suitable for projects not yet running (get things working correctly first via gsap-core/gsap-timeline before optimizing); not suitable for scenarios requiring performance measurement or automated profiling (provides rules, not tooling); not suitable for projects using CSS Animations instead of GSAP (some conceptual tips transfer, but API-specific advice like quickTo/stagger does not apply).
    Install Agent-Ready
    ① Verified Mirror 2026-09-15
    Option A · Direct DownloadDownload gsap-performance.tar.gz
    sha256: a5bb2ad20a79ec59…
    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.