motion

Motion

概要

Motion（パッケージ：motion、旧称：framer-motion）は、標準的な React アニメーションライブラリです。motion/react からインポートします。ジェスチャー、スクロール連動アニメーション、レイアウト遷移、SVG パスの描画、スプリング物理演算のための宣言的なプロパティを提供します。ハイブリッドアニメーションエンジンを使用しています（変形／不透明度には WAAPI、スクロール連動効果には ScrollTimeline を使用）。バンドルサイズは 2.3 KB（useAnimate mini）から 34 KB（フル版）までで、LazyMotion を使うと 4.6 KB まで最適化できます。React 18.2 以降、React 19、Next.js App Router、Vite に対応しています。

単純なリスト項目の追加／削除アニメーションには Motion を使用しないでください（代わりに 3.28 KB の AutoAnimate を使用してください）。3D には使用しないでください（代わりに Three.js ／ React Three Fiber を使用してください）。

クイックリファレンス

パターン	API ／プロパティ
マウント時にフェードイン	initial、animate、transition
終了アニメーション	AnimatePresence + exit プロパティ（固有の key が必要）
リストのスタッガー表示	staggerChildren を指定した variants
ホバー／タップ／フォーカス	whileHover、whileTap、whileFocus
ドラッグ	drag、dragConstraints、dragElastic
スクロールをトリガーにする	whileInView、viewport={{ once: true }}
スクロール連動／視差効果	useScroll + useTransform
進捗インジケーター	scrollYProgress + scaleX
レイアウトアニメーション	layout プロパティ（FLIP 技法）
共有要素	layoutId（ビュー間で同じ ID を使用）
レイアウトグループ	同階層のリストを囲む LayoutGroup
ページ遷移	AnimatePresence + key={pathname}
SVG パスの描画	motion.path の pathLength
カウンターアニメーション	useSpring + useTransform
命令型の制御	useAnimate フックが [scope, animate] を返す
カスタムコンポーネント	motion.create(Component) で任意のコンポーネントをラップ
バンドルの最適化	LazyMotion + domAnimation + m コンポーネント（4.6 KB）
モーションの低減	MotionConfig reducedMotion="user"

よくある間違い

間違い	正しいパターン
条件分岐の内側に AnimatePresence を置く	AnimatePresence をマウントしたままにし、条件付きコンテンツをその内側に置く
AnimatePresence の子に固有の key がない	終了アニメーションのため、各直接の子に固有の key を追加する
Motion の animate プロパティと Tailwind の transition-* クラスを併用する	カクつきを防ぐため、Tailwind の transition クラスを削除する
framer-motion からインポートする	import { motion } from "motion/react" を使用する（2024 年後半に名称変更）
仮想化せずに 50 個以上の項目をアニメーションさせる	大きなリストには react-window または @tanstack/react-virtual を使用する
単純なアニメーションにフル版の 34 KB バンドルを使う	LazyMotion + domAnimation（4.6 KB）または useAnimate（2.3 KB）を使用する
Next.js App Router で "use client" を指定していない	ディレクティブを追加するか、motion/react-client からインポートする
width／height を直接アニメーションさせる	GPU アクセラレーションのために layout プロパティまたは transform: scale を使用する
prefers-reduced-motion に対応していない	アプリを MotionConfig reducedMotion="user" でラップする

委任

• アニメーションのパフォーマンスとバンドルサイズを監査する：Explore エージェントを使用して、サイズの大きいインポート、LazyMotion の不足、リフローを引き起こすプロパティを見つけます
• 複雑な複数ステップのアニメーションを構築する：Task エージェントを使用して、スクロール連動の視差効果、共有レイアウトのトランジション、段階的なシーケンスを構築します
• 新しいプロジェクトのアニメーションアーキテクチャを計画する：Plan エージェントを使用して、要件に基づいて Motion、AutoAnimate、CSS のみの方式を評価します

design-system スキルが利用可能な場合は、アニメーションのトークン定義とモーションデザインのガイドラインを委任します。

参考資料

• コアパターン -- アニメーションパターン：フェード、終了、段階表示、ジェスチャー、モーダル、アコーディオン、タブ、スクロール、レイアウト、ドラッグ、SVG、読み込み
• スクロールアニメーション -- useScroll、useTransform、スクロールトリガー、視差効果、進行状況インジケーター、オフセット設定
• パフォーマンス -- LazyMotion、useAnimate、ハードウェアアクセラレーション、仮想化、本番環境向けチェックリスト
• Next.js との統合 -- App Router のパターン、motion/react-client、Pages Router、既知の問題
• アクセシビリティと CSS -- prefers-reduced-motion、MotionConfig、useReducedMotion、CSS キーフレーム、Tailwind アニメーション
• ライブラリ選定ガイド -- Motion と AutoAnimate の選定ガイド。機能比較とユースケースの推奨事項を掲載
• トラブルシューティング -- AnimatePresence の不具合、Tailwind との競合、レイアウトの問題、React 19 の問題、命名の移行