Design & Motion · greensock/gsap-skills

gsap-utils

Name: gsap-utils
Author: greensock/gsap-skills

Official GSAP skill for gsap.utils — clamp, mapRange, normalize, interpolate, random, snap, toArray, wrap, pipe. Use when the user asks about gsap.utils, clamp, mapRange, random, snap, toArray, wrap, or helper utilities in GSAP.

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

Position gsap.utils as a "pure-function utility toolbox requiring no registration" and explain its injection points within animation workflows (function-based values, ScrollTrigger/Observer callbacks).

skills/gsap-utils/SKILL.md

**gsap.utils** provides pure helpers; no need to register.

Why it delivers claimed functionality: utils consists of pure computational APIs with no side effects or network requests. The skill's value lies in providing explicit input-to-output semantics for each function, preventing the model from hand-writing ad-hoc arithmetic in scenarios like scroll position mapping, randomization, and grid snapping.

Standardize the invocation paradigm of "omitting values returns a reusable function", while highlighting the sole exception of passing true to random().

skills/gsap-utils/SKILL.md

If you omit that argument, the util returns a **function** that accepts the value later.

This reflects the design consistency across utils: clamp, mapRange, normalize, interpolate, snap, wrap, and wrapYoyo all support curried/functional forms. random uses a trailing true to return a function due to its different signature (having a snapIncrement parameter). Explicitly stating this exception prevents the model from applying the wrong invocation pattern.

Provide concrete "input → output comments" for each function as behavioral specifications (essentially verifiable micro-tests), allowing the model to align its semantics with concrete examples.

skills/gsap-utils/SKILL.md

gsap.utils.clamp(0, 100, 150); // 100

For example, normalize(0, 100, 50) // 0.5, snap(10, 23) // 20, or interpolate("#ff0000", "#0000ff", 0.5) // mid color. Such deterministic comments let the model validate value trajectories on its own, making it far more reliable than prose descriptions.

Break down distribute() into tabular configuration parameters (base, amount, each, from, grid, axis, ease), representing the internal distribution engine of GSAP stagger.

skills/gsap-utils/SKILL.md

**Returns a function** that assigns a value to each target based on its position in the array (or in a grid).

It supports two usage patterns: directly as a tween property value (where GSAP invokes it per target with (index, target, targets)) or manual invocation by index. Combined with grid + axis, it enables 2D ripple effects.

Introduce selector(scope) as the official primitive for an in-component "selector sandbox", aligning with the scoping disciplines of gsap-react and gsap-frameworks.

skills/gsap-utils/SKILL.md

Returns a scoped selector function that finds elements only within the given element (or ref).

It accepts DOM elements or refs (handling .current internally). In React or Vue, containerRef can be passed directly to prevent global selector leaks that unintentionally affect other page nodes.

Dedicate a section to unit and color parsing: getUnit, unitize, and splitColor handle inputs beyond pure numbers, clarifying that mapRange and normalize do not perform unit conversions.

skills/gsap-utils/SKILL.md

❌ Assume **mapRange** / **normalize** handle units; they work on numbers.

splitColor supports rgb, rgba, hsl, hsla, hex, and named colors, returning HSL when the second parameter is true—useful for per-channel color interpolation or gradient generation.

2Core Capabilities

01Range mapping and normalization: clamp / mapRange / normalize / interpolate (numbers, colors, objects)

02Randomization and snapping: random (with snapIncrement and array sampling) / snap (numbers or arrays) / shuffle

03In-tween string-format randomization: x: "random(-100, 100, 5)", evaluated by GSAP per target

04distribute(): distribute values by index, grid, or easing (the engine behind advanced stagger, callable manually)

05Units and colors: getUnit / unitize / splitColor (including HSL output)

06Collections and scoping: selector(scope) / toArray(value, scope) to convert mixed inputs into true arrays

07Function composition and wrapping: pipe(...fns) (pipeline), wrap / wrapYoyo (looping/yoyo wrapping)

3External Dependencies

Kind	Dependency / Endpoint
package	gsap（utils 为内核自带命名空间，无需注册）
network	distribute() 官方文档
network	random() 官方文档
network	splitColor() 官方文档与 HelperFunctions 列表页

4Recommended Governance & Evidence

Suggested Controls for Safe Operation

For Agent Runtime

Can be auto-loaded

For Administrators

Evidence & Triggers (File Paths & Excerpts)

SKILL.md: Pure prompt instructions and rule text with no script execution or external impact

Audit Notes: Pure instruction-based skill: the directory contains only SKILL.md (12,093 B) with no scripts, outbound network requests, credential reading, or file writes; external links consist of 4 official gsap.com documentation URLs. It consists entirely of functional descriptions for math, collections, and unit transformations, making it the least likely skill in this repository to exceed permissions. The only caveat is that mistakenly treating the closure returned by functional currying as a scalar value (e.g., comparing it numerically) will cause animations to fail silently—a functional usage boundary rather than a security concern.

5Second-Pass Verification

[ok] 目录资产面：仅 SKILL.md — skills/gsap-utils/ 下唯一文件 SKILL.md（12,093 B）；无 scripts/、references/、数据文件。
[ok] external_deps 逐条核实 — gsap 包依赖证据取自 README 安装段；三条 gsap.com 链接（distribute、random()、HelperFunctions）+ splitColor 链接在内文中逐字命中。
[ok] 函数签名与示例输出是否与官方语义一致 — 抽查 clamp(0,100,150)=100、mapRange(0,100,0,500,50)=250、normalize(0,100,50)=0.5、snap(10,23)=20、wrap(0,360,370)=10、wrapYoyo(0,100,150)=50，均与 GSAP 官方 API 语义吻合，无编造。
[ok] 「random 是唯一例外」的说法是否可复核 — 原文明确「This is the only util that uses `true` for the function form instead of omitting the value.」并给出 random(-200,500,10,true) 示例，叙述自洽。
[ok] 安全反例搜索 — token 扫描：curl/wget/fetch(/XMLHttpRequest/exec(/child_process/process.env/.env/API_KEY/secret 零命中；无混淆代码（该文件只有短代码块）。
[ok] 与 gsap-react / gsap-frameworks 的 scoping 叙述是否一致 — 本文件「Use **gsap.utils.selector(scope)** in components so selectors are scoped to a container or ref.」与 gsap-react 的「always pass scope」、gsap-frameworks 的「Do not use global selectors」同向。
[ok] 元数据与 pin — frontmatter license: MIT；本地 HEAD = aed9cfd3277740755f6bfc1155c7aa645403b760；GitHub API stars 15326、pushed_at 2026-07-29T17:36:08Z。
[ok] 无夸大检查 — description 只声明「Official GSAP skill for gsap.utils …」，文件内容即函数清单与示例，无越界承诺（不宣称性能优化或自动重构）。

6Verdict & Scenarios

Consolidates scattered utility functions into an organized reference: range mapping, random snapping, distribution, unit/color handling, and collection scoping across five major categories.

Comments serve as assertions: every API entry includes deterministic input-to-output examples, allowing models to self-verify rather than misinterpreting prose definitions.

Unified functional paradigm with explicit exceptions reduces invocation syntax errors.

Covers distribute() as the advanced stagger engine, generating grid- and ease-distributed values without writing custom index math.

Provides official primitives for component scope safety: selector(scope) / toArray(value, scope), closing the loop with React/Vue scoping disciplines.

Best for: Ideal for any GSAP project requiring scroll-progress-to-value mapping, randomization/snapping, staggered grid distribution, scoped selectors, or color channel interpolation. It serves as the most practical companion skill when authoring ScrollTrigger callbacks or complex staggers.

Not for: Not intended as a general animation tutorial (it does not teach tweens or timelines and requires gsap-core/gsap-timeline fundamentals); not suitable for non-GSAP projects (functions reside under the gsap.utils namespace); not intended for runtime type validation or performance profiling.

Install Agent-Ready

① Verified Mirror 2026-09-15

Option A · Direct DownloadDownload gsap-utils.tar.gz

sha256: 55bd8167106fd1d2…

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.