Motion Avancé
Motifs d'animation complexes, interactifs et basés sur la physique.
Nécessite d'avoir d'abord configuré motion-foundations.
À utiliser lorsque motion-patterns ne suffit pas.
Quand l'activer
- Créer des feuilles glisser-pour-fermer, des gestes de balayage ou des listes réorganisables
- Animer du texte mot par mot, caractère par caractère, ou comme un compteur en direct
- Dessiner des chemins SVG, faire du morphing d'icônes ou animer une progression circulaire
- Écrire un hook d'animation personnalisé (
useScrollReveal, bouton magnétique, suivi du curseur) - Organiser des animations multi-étapes de manière impérative avec
useAnimate - Construire des spinners, des squelettes shimmer, des indicateurs de pulsation ou des états de chargement de boutons
Résultats produits
Cette compétence produit :
- Interactions de glisser : cartes glissables, feuilles glisser-pour-fermer, listes
Reorder.Group - Hooks de gestes : détection de balayage, appui long, contour de pincement
- Composants d'animation de texte : révélation de mot, machine à écrire par caractère, compteur numérique
- Animation SVG : dessin de chemin, morphing d'icône, anneau de progression de trait
- Hooks personnalisés :
useScrollReveal,useHoverScale,useNavigationDirection,useInViewOnce - Séquences impératives via
useAnimateavecasync/awaitinterruptible - Composants de chargeur : spinner, shimmer, point de pulsation, barre de progression, état de chargement de bouton
Principes
- Le mouvement basé sur la physique (
useSpring,springs.*) est toujours plus naturel que celui basé sur la durée pour la manipulation directe. useMotionValue+useTransformcalcule des valeurs dérivées sans déclencher de rendus.- Les séquences
useAnimatesont impératives et interruptibles — appeleranimate()en cours d'exécution annule automatiquement l'animation précédente. - Les valeurs de mouvement (
useMotionValue,useSpring) sont compatibles SSR et ne provoquent pas d'erreurs d'hydratation.
Règles
- Les interactions de glisser doivent être testées sur les appareils tactiles, pas seulement à la souris. La propriété
dragfonctionne sur les deux mais la sensation et le seuil diffèrent. - Les animations infinies doivent se mettre en pause lorsque
document.visibilityState === "hidden". Les onglets en arrière-plan ne doivent pas consommer de GPU/CPU. - Le seuil de balayage doit être explicite. Ne jamais déduire l'intention uniquement de la vélocité ; combiner les vérifications
offset+velocity. - La référence de portée
useAnimatedoit être attachée à un élément DOM monté. Appeleranimate()avant le montage échoue silencieusement. - Les valeurs de mouvement ne doivent pas être recréées lors du rendu.
useMotionValue(0)à l'intérieur d'un composant est correct ;new MotionValue(0)dans un rendu ne l'est pas. - Toutes les valeurs de tokens sont importées de
motion-foundations. Pas de nombres en ligne. - Les hooks personnalisés doivent gérer le nettoyage. Chaque
window.addEventListenera besoin d'unremoveEventListenercorrespondant dans le retour deuseEffect. - Le morphing SVG nécessite des nombres de commandes de chemin égaux. Les chemins avec des structures de commandes différentes se figent au lieu d'interpoler.
Guide de décision
Choisir la bonne API avancée
| Scénario | API |
|---|---|
| Glisser avec physique au relâchement | drag + dragTransition: springs.release |
| Liste réorganisable ordonnée | Reorder.Group + Reorder.Item |
| Fermeture sur décalage de glisser | drag="y" + vérification du décalage onDragEnd |
| Balayage gauche/droite | drag="x" + vérification du décalage onDragEnd |
| Appui long | Hook useLongPress |
| Valeur lissée dans le temps | useSpring |
| Valeur dérivée d'une autre | useTransform |
| Séquence multi-étapes | useAnimate avec async/await |
| Animation impérative unique | animate() depuis motion |
| Texte apparaissant mot par mot | Stagger sur des spans inline-block |
| Dessin SVG activé | pathLength 0 → 1 |
| Morphing SVG | Interpolation de l'attribut d (commandes égales) |
| Progression circulaire | Interpolation de strokeDashoffset |
Quand utiliser useSpring vs une transition spring
useSpring | transition: springs.* | |
|---|---|---|
| À utiliser pour | Suivi du curseur, valeurs suivies par le pointeur | Changements d'état discrets |
| Mises à jour | Continues, à chaque frame | Déclenchées par un changement d'état |
| Interruption | Lisse — la physique reprend depuis la vélocité | Redémarrage depuis la valeur actuelle |
Concepts clés
useMotionValue + useTransform
Calcul réactif sans rendus :
const x = useMotionValue(0)
const opacity = useTransform(x, [-200, 0, 200], [0, 1, 0])
// l'opacité se met à jour à chaque frame lorsque x change — pas de setState, pas de rendu
useAnimate
Renvoie [scope, animate]. La référence de portée doit être attachée à un élément DOM.
Les appels à animate() sont interruptibles — appeler en cours d'exécution annule l'exécution précédente.
const [scope, animate] = useAnimate()
async function play() {
await animate(".step-1", { opacity: 1 }, { duration: 0.3 })
await animate(".step-2", { x: 0 }, { duration: 0.4 })
animate(".step-3", { scale: 1 }, { duration: 0.25 }) // fire and forget
}
return <div ref={scope}>...</div>
Exemples de code
Carte glissable
"use client"
import { motion } from "motion/react"
import { springs, motionTokens } from "@/lib/motion-tokens"
<motion.div
drag
dragConstraints={{ left: -100, right: 100, top: -100, bottom: 100 }}
dragElastic={0.1}
whileDrag={{
scale: motionTokens.scale.pop,
boxShadow: "0 16px 40px rgba(0,0,0,0.2)",
}}
dragTransition={springs.release}
/>
Feuille glisser-pour-fermer
"use client"
import { motion, useMotionValue, useTransform } from "motion/react"
export function BottomSheet({ onClose }: { onClose: () => void }) {
const y = useMotionValue(0)
const opacity = useTransform(y, [0, 200], [1, 0])
return (
<motion.div
drag="y"
dragConstraints={{ top: 0 }}
style={{ y, opacity }}
onDragEnd={(_, info) => {
// Règle 3 : combiner offset + velocity
if (info.offset.y > 120 || info.velocity.y > 500) onClose()
}}
/>
)
}
Liste réorganisable
"use client"
import { Reorder } from "motion/react"
export function SortableList() {
const [items, setItems] = useState(initialItems)
return (
<Reorder.Group axis="y" values={items} onReorder={setItems}>
{items.map((item) => (
<Reorder.Item key={item.id} value={item}>
{item.label}
</Reorder.Item>
))}
</Reorder.Group>
)
}
Détection de balayage
"use client"
import { motion } from "motion/react"
const OFFSET_THRESHOLD = 50
const VELOCITY_THRESHOLD = 300
<motion.div
drag="x"
dragConstraints={{ left: 0, right: 0 }}
onDragEnd={(_, info) => {
const swipedRight = info.offset.x > OFFSET_THRESHOLD || info.velocity.x > VELOCITY_THRESHOLD
const swipedLeft = info.offset.x < -OFFSET_THRESHOLD || info.velocity.x < -VELOCITY_THRESHOLD
if (swipedRight) onSwipeRight()
if (swipedLeft) onSwipeLeft()
}}
/>
Hook d'appui long
import { useRef } from "react"
export function useLongPress(callback: () => void, ms = 600) {
const timerRef = useRef<ReturnType<typeof setTimeout>>()
return {
onPointerDown: () => { timerRef.current = setTimeout(callback, ms) },
onPointerUp: () => clearTimeout(timerRef.current),
onPointerLeave: () => clearTimeout(timerRef.current),
}
}
Révélation mot par mot
"use client"
import { motion } from "motion/react"
import { springs } from "@/lib/motion-tokens"
export function AnimatedText({ text }: { text: string }) {
return (
<motion.p
variants={{ visible: { transition: { staggerChildren: 0.05 } } }}
initial="hidden"
animate="visible"
>
{text.split(" ").map((word, i) => (
<motion.span
key={i}
className="inline-block mr-1"
variants={{
hidden: { opacity: 0, y: 12 },
visible: { opacity: 1, y: 0, transition: springs.gentle },
}}
>
{word}
</motion.span>
))}
</motion.p>
)
}
Compteur numérique
"use client"
import { useRef, useEffect } from "react"
import { animate } from "motion"
import { motionTokens } from "@/lib/motion-tokens"
export function Counter({ to }: { to: number }) {
const nodeRef = useRef<HTMLSpanElement>(null)
useEffect(() => {
const controls = animate(0, to, {
duration: motionTokens.duration.crawl,
ease: motionTokens.easing.smooth,
onUpdate: (v) => {
if (nodeRef.current) nodeRef.current.textContent = Math.round(v).toString()
},
})
return controls.stop // Règle 7 : nettoyage
}, [to])
return <span ref={nodeRef} />
}
Dessin de chemin SVG
"use client"
import { motion } from "motion/react"
import { motionTokens } from "@/lib/motion-tokens"
<motion.path
d="M 0 100 Q 50 0 100 100"
initial={{ pathLength: 0, opacity: 0 }}
animate={{ pathLength: 1, opacity: 1 }}
transition={{ duration: motionTokens.duration.slow, ease: motionTokens.easing.smooth }}
/>
Anneau de progression de trait
"use client"
import { motion } from "motion/react"
import { motionTokens } from "@/lib/motion-tokens"
const CIRCUMFERENCE = 2 * Math.PI * 40 // r=40
export function ProgressRing({ progress }: { progress: number }) {
return (
<svg width="100" height="100" viewBox="0 0 100 100">
<circle cx="50" cy="50" r="40" fill="none" stroke="#e5e7eb" strokeWidth="8" />
<motion.circle
cx="50" cy="50" r="40"
fill="none" stroke="#6366f1" strokeWidth="8"
strokeLinecap="round"
strokeDasharray={CIRCUMFERENCE}
animate={{ strokeDashoffset: CIRCUMFERENCE - (progress / 100) * CIRCUMFERENCE }}
transition={{ duration: motionTokens.duration.normal, ease: motionTokens.easing.smooth }}
style={{ rotate: -90, transformOrigin: "center" }}
/>
</svg>
)
}
Hook useScrollReveal
"use client"
import { useRef } from "react"
import { useScroll, useTransform } from "motion/react"
import { motionTokens } from "@/lib/motion-tokens"
export function useScrollReveal() {
const ref = useRef(null)
const { scrollYProgress } = useScroll({ target: ref, offset: ["start end", "end start"] })
const opacity = useTransform(scrollYProgress, [0, 0.3], [0, 1])
const y = useTransform(scrollYProgress, [0, 0.3], [motionTokens.distance.lg, 0])
return { ref, style: { opacity, y } }
}
// Utilisation
const { ref, style } = useScrollReveal()
<motion.section ref={ref} style={style} />
Suivi du curseur
"use client"
import { useEffect } from "react"
import { motion, useMotionValue, useSpring } from "motion/react"
import { springs } from "@/lib/motion-tokens"
export function CursorFollower() {
const x = useMotionValue(-100)
const y = useMotionValue(-100)
const sx = useSpring(x, springs.gentle)
const sy = useSpring(y, springs.gentle)
useEffect(() => {
const move = (e: MouseEvent) => { x.set(e.clientX); y.set(e.clientY) }
window.addEventListener("mousemove", move)
return () => window.removeEventListener("mousemove", move) // Règle 7
}, [])
return (
<motion.div
className="fixed top-0 left-0 w-6 h-6 rounded-full bg-indigo-500
pointer-events-none -translate-x-1/2 -translate-y-1/2 z-50"
style={{ x: sx, y: sy }}
/>
)
}
Squelette shimmer
"use client"
import { useEffect } from "react"
import { motion, useAnimation } from "motion/react"
import { motionTokens } from "@/lib/motion-tokens"
export function ShimmerSkeleton({ className = "" }: { className?: string }) {
const controls = useAnimation()
useEffect(() => {
const play = () =>
controls.start({
x: ["-100%", "100%"],
transition: {
repeat: Infinity,
duration: motionTokens.duration.crawl,
ease: motionTokens.easing.linear,
},
})
const handleVisibility = () => {
if (document.visibilityState === "hidden") controls.stop()
else void play()
}
void play()
document.addEventListener("visibilitychange", handleVisibility)
return () => {
controls.stop()
document.removeEventListener("visibilitychange", handleVisibility)
}
}, [controls])
return (
<div className={`relative overflow-hidden bg-gray-200 rounded ${className}`}>
<motion.div
className="absolute inset-0 bg-gradient-to-r from-transparent via-white/60 to-transparent"
initial={{ x: "-100%" }}
animate={controls}
/>
</div>
)
}
État de chargement de bouton
"use client"
import { motion, AnimatePresence } from "motion/react"
import { motionTokens, springs } from "@/lib/motion-tokens"
export function LoadingButton({
loading,
label,
onClick,
}: {
loading: boolean
label: string
onClick: () => void
}) {
return (
<motion.button
onClick={onClick}
animate={{ opacity: loading ? 0.7 : 1 }}
whileTap={loading ? {} : { scale: motionTokens.scale.press }}
transition={springs.snappy}
disabled={loading}
>
<AnimatePresence mode="wait">
{loading ? (
<motion.span
key="loading"
initial={{ opacity: 0 }} animate={{ opacity: 1 }} exit={{ opacity: 0 }}
transition={{ duration: motionTokens.duration.fast }}
>
…
</motion.span>
) : (
<motion.span
key="label"
initial={{ opacity: 0 }} animate={{ opacity: 1 }} exit={{ opacity: 0 }}
transition={{ duration: motionTokens.duration.fast }}
>
{label}
</motion.span>
)}
</AnimatePresence>
</motion.button>
)
}
Animation infinie avec pause de visibilité
"use client"
import { useEffect } from "react"
import { motion, useAnimation } from "motion/react"
import { motionTokens } from "@/lib/motion-tokens"
export function PulseDot() {
const controls = useAnimation()
useEffect(() => {
const pulse = () =>
controls.start({
scale: [1, 1.4, 1],
opacity: [1, 0.6, 1],
transition: { repeat: Infinity, duration: motionTokens.duration.crawl },
})
// Règle 2 : pause lorsque l'onglet est caché
const handleVisibility = () => {
if (document.visibilityState === "hidden") controls.stop()
else void pulse()
}
void pulse()
document.addEventListener("visibilitychange", handleVisibility)
return () => {
controls.stop()
document.removeEventListener("visibilitychange", handleVisibility)
}
}, [controls])
return <motion.div animate={controls} className="w-3 h-3 rounded-full bg-indigo-500" />
}