motion-react

React 向け Motion

パッケージ：motion（以前の名称は framer-motion）。"motion/react" からインポートします。

インストール

pnpm add motion

インポート

// Standard React (Vite, CRA, Pages Router)
import { motion, AnimatePresence } from "motion/react"

// Next.js App Router — use "motion/react-client" for RSC tree-shaking
"use client"
import * as motion from "motion/react-client"

// Minimal bundle (2.3 KB) — imperative API only
import { useAnimate } from "motion/react-mini"

// Reduced bundle (4.6 KB) — LazyMotion + m component
import { LazyMotion, domAnimation, m } from "motion/react"

Motion コンポーネント

すべての HTML/SVG 要素に、対応する motion コンポーネントがあります。

<motion.div />
<motion.button />
<motion.svg />
<motion.circle />

カスタムコンポーネントの場合は、motion.create() でラップします。

const MotionBox = motion.create(Box)
// forwardRef required — the ref must reach a DOM node

アニメーションの主要な Props

<motion.div
  initial={{ opacity: 0, y: 20 }}     // mount state (or false to skip)
  animate={{ opacity: 1, y: 0 }}      // target state
  exit={{ opacity: 0, y: -20 }}       // unmount state (needs AnimatePresence)
  transition={{ type: "spring", bounce: 0.25 }}
  whileHover={{ scale: 1.05 }}
  whileTap={{ scale: 0.95 }}
  whileFocus={{ borderColor: "#00f" }}
  whileDrag={{ scale: 1.1 }}
  whileInView={{ opacity: 1 }}
  viewport={{ once: true, margin: "-100px" }}
/>

アニメーション可能な値

Motion は、opacity、filter、background-image、mask-image など、あらゆる CSS 値をアニメーションできます。

独立したトランスフォーム（CSS だけでは実現できません）：

• 移動：x、y、z
• 拡大縮小：scale、scaleX、scaleY
• 回転：rotate、rotateX、rotateY、rotateZ
• 傾斜：skewX、skewY
• 原点：originX、originY、originZ

値の型：数値、単位付き文字列（"100px"）、色（hex/rgba/hsla）、幅や高さに指定する "auto"。

ハードウェアアクセラレーション：GPU コンポジットを有効にするには、transform を直接設定します。

<motion.li
  initial={{ transform: "translateX(-100px)" }}
  animate={{ transform: "translateX(0px)" }}
  transition={{ type: "spring" }}
/>

キーフレーム

配列を渡して、一連のアニメーションを実行します。

<motion.div animate={{ x: [0, 100, 0] }} />

// null = "use current value"
<motion.div animate={{ x: [null, 100, 0] }} />

バリアント

連携したアニメーションに使用する、名前付きのアニメーション状態です。

const list = {
  visible: {
    transition: { staggerChildren: 0.1 }
  },
  hidden: {}
}

const item = {
  visible: { opacity: 1, y: 0 },
  hidden: { opacity: 0, y: 20 }
}

<motion.ul initial="hidden" animate="visible" variants={list}>
  <motion.li variants={item} />
  <motion.li variants={item} />
</motion.ul>

バリアントはツリー内に伝播します。子要素は親の animate／initial／exit を継承します。

AnimatePresence — 終了時のアニメーション

import { AnimatePresence } from "motion/react"

<AnimatePresence>
  {isVisible && (
    <motion.div
      key="modal"           // REQUIRED: unique key
      initial={{ opacity: 0 }}
      animate={{ opacity: 1 }}
      exit={{ opacity: 0 }}
    />
  )}
</AnimatePresence>

重要なルール：

1. AnimatePresence はマウントされた状態を維持する必要があります。条件分岐で囲まないでください
2. 直接の子要素には、それぞれ一意の key prop が必要です
3. exit prop が機能するのは、AnimatePresence 内の motion コンポーネントのみです

// WRONG — AnimatePresence unmounts with condition
{show && <AnimatePresence><motion.div /></AnimatePresence>}

// CORRECT — condition inside AnimatePresence
<AnimatePresence>{show && <motion.div key="k" />}</AnimatePresence>

モード："sync"（デフォルト）、"wait"（順番に開始／終了）、"popLayout"（終了する要素をフローからポップアウト）。

スライドショーのパターン — key を変更して、終了と開始のアニメーションを実行します。

<AnimatePresence mode="wait">
  <motion.img
    key={image.src}
    initial={{ x: 300, opacity: 0 }}
    animate={{ x: 0, opacity: 1 }}
    exit={{ x: -300, opacity: 0 }}
  />
</AnimatePresence>

動的な終了データ — custom prop と usePresenceData を介して渡します。

<AnimatePresence custom={direction}>
  <Slide key={id} />
</AnimatePresence>

// Inside Slide:
const direction = usePresenceData()

トランジション

トランジション API の詳細は、references/transitions-api.md を参照してください。

クイックリファレンス：

// Spring (default for physical props: x, y, scale)
transition={{ type: "spring", bounce: 0.25 }}
transition={{ type: "spring", stiffness: 300, damping: 20 }}
transition={{ type: "spring", visualDuration: 0.5, bounce: 0.25 }}

// Tween (default for opacity, color)
transition={{ duration: 0.3, ease: "easeInOut" }}

// Per-value transitions
transition={{
  default: { type: "spring" },
  opacity: { duration: 0.2, ease: "linear" }
}}

// Orchestration
transition={{ delay: 0.5, repeat: Infinity, repeatType: "reverse" }}

// Global default
<MotionConfig transition={{ duration: 0.3 }}>

レイアウトアニメーション

レイアウトアニメーションの詳細は、references/layout-animations.md を参照してください。

// Auto-animate any layout change
<motion.div layout />

// Shared element transitions
<motion.div layoutId="underline" />

// Customize layout transition
<motion.div layout transition={{ layout: { duration: 0.3 } }} />

ジェスチャーとドラッグ

ジェスチャー／ドラッグ API の詳細は、references/gestures-and-drag.md を参照してください。

<motion.div
  whileHover={{ scale: 1.1 }}
  whileTap={{ scale: 0.9 }}
  drag                           // enable both axes
  drag="x"                       // constrain to x-axis
  dragConstraints={{ left: -100, right: 100 }}
  dragElastic={0.2}
/>

スクロールアニメーション

スクロール API の詳細は、references/scroll-animations.md を参照してください。

// Viewport-triggered
<motion.div
  initial={{ opacity: 0, y: 50 }}
  whileInView={{ opacity: 1, y: 0 }}
  viewport={{ once: true }}
/>

// Scroll-linked progress bar
const { scrollYProgress } = useScroll()
<motion.div style={{ scaleX: scrollYProgress }} />

// Element scroll progress
const ref = useRef(null)
const { scrollYProgress } = useScroll({
  target: ref,
  offset: ["start end", "end start"]
})

フックと Motion 値

フック API の詳細は、references/hooks-and-motion-values.md を参照してください。

// Manual motion values (no re-renders)
const x = useMotionValue(0)
const opacity = useTransform(x, [-200, 0, 200], [0, 1, 0])
<motion.div drag="x" style={{ x, opacity }} />

// Smooth spring following
const springX = useSpring(x, { stiffness: 100, damping: 30 })

// Imperative animation control
const [scope, animate] = useAnimate()
animate("li", { opacity: 1 }, { stagger: 0.1 })

// Event listener (no re-render)
useMotionValueEvent(scrollY, "change", (v) => console.log(v))

バンドルの最適化

アプローチ	サイズ	利用できる機能
motion/react	~34 KB	フル API
LazyMotion + m	~4.6 KB	宣言的なアニメーション、ジェスチャーなし
motion/react-mini	~2.3 KB	useAnimate のみ

// LazyMotion pattern
import { LazyMotion, domAnimation, m } from "motion/react"

<LazyMotion features={domAnimation}>
  <m.div animate={{ opacity: 1 }} />
</LazyMotion>

アクセシビリティ

<MotionConfig reducedMotion="user">
  <App />
</MotionConfig>

オプション："user"（OS の設定に従う）、"always"（即時に切り替える）、"never"（設定を無視する）。

フック：useReducedMotion() は、ユーザーが視差効果を減らす設定を選んでいる場合に true を返します。

Tailwind との連携

それぞれのライブラリの得意分野を活用してください。競合するため、Tailwind の transition-* クラスは削除してください。

// WRONG — Tailwind transition conflicts with Motion
<motion.div className="transition-all duration-300" animate={{ x: 100 }} />

// CORRECT — Tailwind for styling, Motion for animation
<motion.div className="rounded-lg bg-blue-600 p-4" whileHover={{ scale: 1.05 }} />

Next.js App Router

Motion コンポーネントにはクライアント側のレンダリングが必要です。最適なツリーシェイキングには、"motion/react-client" を使用してください。

// components/motion-client.tsx
"use client"
import * as motion from "motion/react-client"
export { motion }

// app/page.tsx (Server Component)
import { motion } from "@/components/motion-client"
<motion.div animate={{ opacity: 1 }} />

よくある落とし穴

1. 終了時のアニメーションが実行されない — AnimatePresence はマウントされた状態を維持する必要があります。子要素には一意の key が必要です
2. Tailwind のトランジションとの競合 — motion 要素から transition-* クラスを削除してください
3. height: "auto" と display: "none" の併用 — 代わりに visibility: "hidden" を使用してください
4. スクロール可能なコンテナ内でのレイアウトアニメーション — スクロールする親要素に layoutScroll prop を追加してください
5. 固定要素内でのレイアウトアニメーション — 固定された親要素に layoutRoot prop を追加してください
6. パーセント指定のトランスフォームとレイアウトの併用 — ピクセル値に変換してください。パーセント値は FLIP の計算を妨げます
7. popLayout モード — カスタムコンポーネントでは、DOM ノードに ref を渡すために forwardRef を使用する必要があります
8. AnimatePresence の propagate — 子要素の終了アニメーションを実行するには、ネストした AnimatePresence で true に設定してください

References

• Animation API details: references/animation-api.md
• Transition types & spring config: references/transitions-api.md
• Gestures & drag: references/gestures-and-drag.md
• Layout animations: references/layout-animations.md
• Scroll animations: references/scroll-animations.md
• Hooks & motion values: references/hooks-and-motion-values.md