gsap

GSAP のベストプラクティス

モダンなウェブ向けのプロフェッショナル品質の JavaScript アニメーションライブラリです。高性能なトゥイーン、強力なシーケンス機能、スクロールベースのアニメーション、豊富なプラグインエコシステムを提供します。

インストール

# Core library
npm install gsap

# React hook
npm install @gsap/react

# Register plugins (do once at app entry)
import gsap from 'gsap'
import { ScrollTrigger } from 'gsap/ScrollTrigger'
gsap.registerPlugin(ScrollTrigger)

クイックスタート

import gsap from 'gsap'

// Basic tween
gsap.to('.box', { x: 200, duration: 1 })

// From animation
gsap.from('.box', { opacity: 0, y: 50, duration: 0.5 })

// Timeline sequence
const tl = gsap.timeline()
tl.to('.box1', { x: 100 })
  .to('.box2', { x: 100 }, '-=0.5')  // overlap by 0.5s
  .to('.box3', { x: 100 }, '<')       // same start as previous

コアコンセプト

コンセプト	説明
トゥイーン	時間の経過に応じてプロパティを変化させる単一のアニメーションです
タイムライン	トゥイーンを正確に制御しながら順序付けるためのコンテナーです
イージング	アニメーションの速度曲線を制御します（デフォルト：power1.out）
ScrollTrigger	アニメーションをスクロール位置に連動させます
プラグイン	GSAP に特化した機能を追加します

リファレンス一覧

リファレンス	使用する場面
references/00-cheatsheet.md	クイックリファレンス。よく使う操作をひと目で確認できます
references/01-core.md	基本的なトゥイーン、特殊プロパティ、コールバック、quickTo、ticker
references/02-easing.md	イージング関数、カスタムイージング
references/03-timeline.md	シーケンス、配置、ラベル、ネスト
references/04-stagger.md	スタッガーアニメーション、グリッドの分布
references/05-utilities.md	ヘルパー関数（toArray、clamp、interpolate）
references/06-scrolltrigger.md	スクロールベースのアニメーション、ピン留め、スクラブ、スナップ
references/07-scrollsmoother.md	スムーズスクロール、視差効果
references/08-splittext.md	テキストの分割とアニメーション
references/09-svg-plugins.md	DrawSVG、MorphSVG、MotionPath
references/10-flip.md	レイアウトアニメーション（FLIP 手法）
references/11-react.md	useGSAP フック、クリーンアップ、React のパターン
references/12-observer-draggable.md	ジェスチャー検出、ドラッグ可能な要素
references/13-text-plugins.md	TextPlugin、ScrambleTextPlugin

よく使うパターン

読み込み時にフェードイン

gsap.from('.hero', {
  opacity: 0,
  y: 30,
  duration: 1,
  ease: 'power2.out'
})

リストのスタッガーアニメーション

gsap.from('.list-item', {
  opacity: 0,
  y: 20,
  stagger: 0.1,
  duration: 0.5
})

スクロールでトリガーされるアニメーション

gsap.registerPlugin(ScrollTrigger)

gsap.to('.box', {
  x: 500,
  scrollTrigger: {
    trigger: '.box',
    start: 'top 80%',
    end: 'top 20%',
    scrub: true
  }
})

コントロール付きタイムライン

const tl = gsap.timeline({ paused: true })
tl.to('.modal', { opacity: 1, scale: 1, duration: 0.3 })
  .from('.modal-content', { y: 20, opacity: 0 }, '-=0.1')

// Control playback
tl.play()
tl.reverse()
tl.progress(0.5)

避けるべき重大なミス

1. プラグインの登録漏れ

// ❌ Plugin won't work
import { ScrollTrigger } from 'gsap/ScrollTrigger'
gsap.to('.box', { scrollTrigger: { ... } })

// ✅ Register plugins first
gsap.registerPlugin(ScrollTrigger)
gsap.to('.box', { scrollTrigger: { ... } })

2. React のクリーンアップに関する問題

// ❌ Memory leaks, zombie animations
useEffect(() => {
  gsap.to('.box', { x: 100 })
}, [])

// ✅ Use useGSAP hook for automatic cleanup
import { useGSAP } from '@gsap/react'
useGSAP(() => {
  gsap.to('.box', { x: 100 })
}, { scope: containerRef })

3. トゥイーンの競合

// ❌ Two tweens fighting for same property
gsap.to('.box', { x: 100, duration: 2 })
gsap.to('.box', { x: 200, duration: 1 })

// ✅ Use overwrite or kill previous
gsap.to('.box', { x: 100, duration: 2, overwrite: true })
// or
gsap.killTweensOf('.box')
gsap.to('.box', { x: 200, duration: 1 })

4. ScrollTrigger が更新されない

// ❌ Layout changes but ScrollTrigger uses old positions
dynamicallyAddContent()

// ✅ Refresh after DOM/layout changes
dynamicallyAddContent()
ScrollTrigger.refresh()

5. 存在しない要素のアニメーション

// ❌ Element not in DOM yet
gsap.to('.dynamic-element', { x: 100 })

// ✅ Wait for element or use immediateRender: false
gsap.to('.dynamic-element', {
  x: 100,
  immediateRender: false,
  scrollTrigger: { ... }
})

6. from() の動作の誤解

// ❌ from() renders immediately, causing flash
gsap.from('.box', { opacity: 0 })

// ✅ Set initial state in CSS or use fromTo
// CSS: .box { opacity: 0; }
gsap.to('.box', { opacity: 1 })

// or use fromTo for explicit control
gsap.fromTo('.box', { opacity: 0 }, { opacity: 1 })

7. セレクターのスコープ指定忘れ

// ❌ Affects ALL .box elements on page
gsap.to('.box', { x: 100 })

// ✅ Scope to container
gsap.to('.box', { x: 100 }, { scope: containerRef })
// or use gsap.utils.selector
const q = gsap.utils.selector(container)
gsap.to(q('.box'), { x: 100 })

クイックリファレンス

タスク	解決策
値に向けてアニメーション	gsap.to(target, { props })
値からアニメーション	gsap.from(target, { props })
両方向にアニメーション	gsap.fromTo(target, { from }, { to })
即座に設定	gsap.set(target, { props })
タイムラインを作成	gsap.timeline({ options })
すべてのトゥイーンを停止	gsap.killTweensOf(target)
グローバルデフォルト	gsap.defaults({ ease, duration })
プラグインを登録	gsap.registerPlugin(Plugin)
ID で取得	gsap.getById('myTween')
メディアクエリに対応	gsap.matchMedia()

プラグインの利用可否

プラグイン	ライセンス	説明
ScrollTrigger	無料	スクロールベースのアニメーション
Observer	無料	ジェスチャー／スクロール検出
Draggable	無料	ドラッグ操作
Flip	無料	レイアウトアニメーション
TextPlugin	無料	テキストコンテンツのアニメーション
ScrollSmoother	Club	スムーズスクロール
SplitText	Club	テキストの分割
DrawSVG	Club	SVG のストロークアニメーション
MorphSVG	Club	SVG のモーフィング
MotionPath	Club	パスに沿った動き
ScrollTo	無料	指定位置へのスクロール