Motion Patterns
最も一般的な UI アニメーションのニーズに対応する、コピー&ペースト可能なパターン集。
ここにあるすべてのパターンは motion-foundations のトークンとスプリングに基づいています。
新たな duration や easing の値を定義せず、それらをインポートしてください。
いつアクティブにするか
- ボタン、カード、モーダル、トースト通知をアニメーションさせる時
- スタッガーを使ったリストの進入アニメーションを構築する時
- Next.js App Router でページトランジションを設定する時
- 条件付きコンテンツに進入・退場アニメーションを追加する時
- スクロール表示、スクロール連動プログレス、スティッキーストーリーセクションを実装する時
- 展開カード、アコーディオン、共有要素トランジションを構築する時
アウトプット
このスキルは以下を生成します:
- アクセシブルで SSR 安全な、すべての標準 UI コンポーネント向けアニメーション
- 正しい退場動作を持つ
AnimatePresenceでラップされた条件付きレンダリング - Next.js App Router 向けのページトランジションラッパーコンポーネント
useScroll+useTransformを使用したスクロール表示・スクロール連動パターン- 展開やクロスフェード要素のためのレイアウトアニメーションパターン(
layout、layoutId)
原則
- すべてのパターンは
motion-foundationsからインポートします。生の数値は使用しません。 - 条件付きレンダリングはすべて
keyとともにAnimatePresenceでラップします。 - 退場アニメーションは常に進入アニメーションと一緒に定義します。後付けにしてはいけません。
layoutは小さく孤立した変化にのみ使用します。大きなサブツリーには明示的なトランスフォームを使用します。
ルール
- 条件付きレンダリングは常に、直接の子要素に
keyを付けてAnimatePresenceでラップします。 key がないと退場アニメーションは決して発火しません。 initial+animateを定義するときは常にexitも定義します。 退場アニメーションがないアニメーションは不完全です。- ページトランジションには
mode="wait"を使用します。 退場が完了するまで進入を開始してはいけません。 - 子要素が約 5 個以上ある、または深くネストされた DOM のサブツリーには
layoutを使用しないでください。 代わりに明示的なx/yトランスフォームを使用します。 - スタッガー間隔は
0.05sから0.10sの間に保ちます。 これより短いと機械的に、長いと動作が鈍く感じられます。 - モーダルには常に以下を含める必要があります: フォーカストラップ、Escape キーで閉じる、スクロールロック、
role="dialog"、aria-modal="true"。 - スクロール表示には
viewport={{ once: true }}を使用します。 スクロールアウト時に繰り返すと、情報提供ではなく気が散ります。 - すべてのトークン値は
motion-foundationsからインポートします。 インラインでの数値使用は禁止です。
判断ガイド
適切なパターンの選択
| 状況 | パターン |
|---|---|
| 要素が表示/非表示になる | AnimatePresence |
| アイテムのリストが順に読み込まれる | スタッガーバリアント |
| ルート間を移動する | ページトランジションラッパー |
| 要素がその場でサイズ変更する | layout プロパティ |
| 同じ要素がページコンテキスト間を移動する | layoutId |
| 要素がスクロールでビューに入ったとき | whileInView |
| 値をスクロール位置に紐づける | useScroll + useTransform |
mode="wait" と mode="sync" の使い分け
| モード | 使用する場面 |
|---|---|
wait | ページトランジション、コンテンツの入れ替え(一度にひとつ) |
sync | 積み重なる通知、リストアイテム(重複しても問題ない) |
popLayout | アイテムがリフローリストから削除される場合 |
コアコンセプト
AnimatePresence の契約
以下の 3 点が常に真である必要があります:
AnimatePresenceが条件付きレンダリングをラップしている- 直接の子要素に
keyがある - 子要素に
exitプロパティがある
これらのいずれかが欠けると、退場アニメーションは警告なしに失敗します。
layout と layoutId の違い
layout— その場での要素自身のサイズ/位置の変化をアニメーション化するlayoutId— 2 つの別々の要素をリンクし、レンダリング間でクロスフェードさせる
展開コンテナ内のテキストには layout="position" を使用して、テキストのリフローがアニメーション化されるのを防ぎます。
コード例
ボタンフィードバック
"use client"
import { motion } from "motion/react"
import { springs, motionTokens } from "@/lib/motion-tokens"
<motion.button
whileHover={{ scale: motionTokens.scale.pop }}
whileTap={{ scale: motionTokens.scale.press }}
transition={springs.snappy}
/>
スタッガーリスト
"use client"
import { motion } from "motion/react"
import { motionTokens, springs } from "@/lib/motion-tokens"
const container = {
hidden: {},
visible: {
transition: {
staggerChildren: 0.08, // 0.05–0.10 ルール内
delayChildren: 0.1,
},
},
}
const item = {
hidden: { opacity: 0, y: motionTokens.distance.md },
visible: { opacity: 1, y: 0, transition: springs.gentle },
}
<motion.ul variants={container} initial="hidden" animate="visible">
{items.map((i) => (
<motion.li key={i.id} variants={item} />
))}
</motion.ul>
モーダル
"use client"
import { motion, AnimatePresence } from "motion/react"
import { motionTokens, springs } from "@/lib/motion-tokens"
// 呼び出し側でラップ:
// <AnimatePresence>{isOpen && <Modal key="modal" />}</AnimatePresence>
export function Modal({ onClose }: { onClose: () => void }) {
return (
<>
{/* オーバーレイ */}
<motion.div
className="fixed inset-0 bg-black/50"
initial={{ opacity: 0 }}
animate={{ opacity: 1 }}
exit={{ opacity: 0 }}
onClick={onClose}
/>
{/* パネル — アクセシビリティ要件: フォーカストラップ、Escape で閉じる、
スクロールロック、role="dialog"、aria-modal="true" */}
<motion.div
role="dialog"
aria-modal="true"
className="fixed inset-x-4 top-1/2 -translate-y-1/2 rounded-xl bg-white p-6"
initial={{
opacity: 0,
scale: motionTokens.scale.press,
y: motionTokens.distance.sm,
}}
animate={{ opacity: 1, scale: 1, y: 0 }}
exit={{
opacity: 0,
scale: motionTokens.scale.press,
y: motionTokens.distance.sm,
}}
transition={springs.gentle}
/>
</>
)
}
トーストスタック
"use client"
import { motion, AnimatePresence } from "motion/react"
import { motionTokens, springs } from "@/lib/motion-tokens"
<AnimatePresence mode="sync">
{toasts.map((t) => (
<motion.div
key={t.id}
layout
initial={{
opacity: 0,
x: motionTokens.distance.xl,
scale: motionTokens.scale.subtle,
}}
animate={{ opacity: 1, x: 0, scale: 1 }}
exit={{
opacity: 0,
x: motionTokens.distance.xl,
scale: motionTokens.scale.subtle,
}}
transition={springs.snappy}
/>
))}
</AnimatePresence>
ページトランジション (Next.js App Router)
// components/page-transition.tsx
"use client"
import { motion, AnimatePresence } from "motion/react"
import { usePathname } from "next/navigation"
import { motionTokens } from "@/lib/motion-tokens"
const variants = {
initial: { opacity: 0, y: motionTokens.distance.sm },
enter: { opacity: 1, y: 0 },
exit: { opacity: 0, y: -motionTokens.distance.sm },
}
export function PageTransition({ children }: { children: React.ReactNode }) {
const pathname = usePathname()
return (
<AnimatePresence mode="wait">
<motion.div
key={pathname}
variants={variants}
initial="initial"
animate="enter"
exit="exit"
transition={{
duration: motionTokens.duration.normal,
ease: motionTokens.easing.smooth,
}}
>
{children}
</motion.div>
</AnimatePresence>
)
}
スクロール表示
"use client"
import { motion } from "motion/react"
import { motionTokens, springs } from "@/lib/motion-tokens"
<motion.div
initial={{ opacity: 0, y: motionTokens.distance.lg }}
whileInView={{ opacity: 1, y: 0 }}
viewport={{ once: true, margin: "-80px" }} // once: true — ルール 7
transition={{ duration: motionTokens.duration.slow, ease: motionTokens.easing.smooth }}
/>
スクロールプログレスバー
"use client"
import { motion, useScroll } from "motion/react"
export function ScrollProgress() {
const { scrollYProgress } = useScroll()
return (
<motion.div
className="fixed top-0 left-0 h-1 bg-indigo-500 origin-left w-full"
style={{ scaleX: scrollYProgress }}
/>
)
}
展開カード
"use client"
import { useState } from "react"
import { motion, AnimatePresence } from "motion/react"
import { springs, motionTokens } from "@/lib/motion-tokens"
export function ExpandingCard({ title, body }: { title: string; body: string }) {
const [expanded, setExpanded] = useState(false)
return (
<motion.div layout onClick={() => setExpanded(!expanded)} className="cursor-pointer">
{/* layout="position" によりテキストのリフローがアニメーション化されるのを防ぐ */}
<motion.h2 layout="position" className="font-semibold">
{title}
</motion.h2>
<AnimatePresence>
{expanded && (
<motion.p
key="body"
initial={{ opacity: 0 }}
animate={{ opacity: 1 }}
exit={{ opacity: 0 }}
transition={{ duration: motionTokens.duration.fast }}
>
{body}
</motion.p>
)}
</AnimatePresence>
</motion.div>
)
}
共有要素クロスフェード
// ソースコンテキスト
<motion.img layoutId="hero-image" src={src} className="w-16 h-16 rounded" />
// 宛先コンテキスト(同じ layoutId — motion がトランジションを処理)
<motion.img layoutId="hero-image" src={src} className="w-full rounded-xl" />
アコーディオン
<motion.div
initial={false}
animate={{ opacity: open ? 1 : 0, scaleY: open ? 1 : 0 }}
style={{ transformOrigin: "top", overflow: "hidden" }}
transition={{
duration: motionTokens.duration.normal,
ease: motionTokens.easing.smooth,
}}
>
{children}
</motion.div>
エンドツーエンドの例
マウント時に進入するスタッガーリストで、条件付きの存在を処理し、動きの抑制設定を尊重します。トークン、スプリング、AnimatePresence、および motion-foundations のアクセシビリティフックを組み合わせています:
"use client"
import { useState } from "react"
import { motion, AnimatePresence } from "motion/react"
import { motionTokens, springs } from "@/lib/motion-tokens"
import { useSafeMotion } from "@/hooks/use-reduced-motion"
const containerVariants = {
hidden: {},
visible: {
transition: { staggerChildren: 0.08, delayChildren: 0.1 },
},
}
function ListItem({ label, onRemove }: { label: string; onRemove: () => void }) {
const safe = useSafeMotion(motionTokens.distance.sm)
return (
<motion.li
variants={{
hidden: safe.initial,
visible: safe.animate,
}}
exit={safe.exit}
transition={springs.gentle}
className="flex items-center justify-between p-3 rounded-lg bg-white shadow-sm"
>
<span>{label}</span>
<button onClick={onRemove}>Remove</button>
</motion.li>
)
}
export function AnimatedList({ items, onRemove }: {
items: { id: string; label: string }[]
onRemove: (id: string) => void
}) {
return (
<motion.ul
variants={containerVariants}
initial="hidden"
animate="visible"
className="space-y-2"
>
<AnimatePresence mode="popLayout">
{items.map((item) => (
<ListItem
key={item.id}
label={item.label}
onRemove={() => onRemove(item.id)}
/>
))}
</AnimatePresence>
</motion.ul>
)
}
制約 / 非対象
このスキルは以下をカバーしません:
- トークンとスプリングの定義 →
motion-foundationsを参照 - ドラッグ操作、スワイプジェスチャー、並べ替え可能リスト →
motion-advancedを参照 - テキストアニメーション(単語/文字の表示、カウンター) →
motion-advancedを参照 - SVG パスの描画またはモーフィング →
motion-advancedを参照 - カスタムアニメーションフック →
motion-advancedを参照 motion/reactを使用しない CSS のみのトランジション
アンチパターン
| アンチパターン | 違反したルール | 修正方法 |
|---|---|---|
AnimatePresence の子要素に key がない | ルール 1 | 直接の子要素に安定した key を追加する |
initial + animate に exit がない | ルール 2 | 常に 3 つすべてを一緒に定義する |
mode="wait" なしのページトランジション | ルール 3 | AnimatePresence に mode="wait" を追加する |
50 アイテムのリストに layout を使用 | ルール 4 | mode="popLayout" または明示的なトランスフォームを使用する |
10 アイテムのリストで staggerChildren: 0.2 | ルール 5 | 0.08–0.10 に制限する |
| フォーカストラップなしのモーダル | ルール 6 | focus-trap-react または Radix Dialog を追加する |
viewport={{ once: true }} なしの whileInView | ルール 7 | 繰り返す進入は情報提供ではなく気が散る |
インラインで transition={{ duration: 0.3 }} | ルール 8 | motionTokens.duration.normal を使用する |
関連スキル
motion-foundations— ここにあるすべてのパターンがインポートする、すべてのトークン、スプリング、useSafeMotionフック、SSR ガードを定義します。最初にセットアップする必要があります。motion-advanced— これらのパターンをドラッグ、ジェスチャー、SVG、テキスト、カスタムフック、命令型シーケンスで拡張します。このスキルのパターンを再定義することはありません。