motion-advanced

Motion Avancé

Motifs d'animation complexes, interactifs et basés sur la physique. Nécessite que motion-foundations soit configuré au préalable. À utiliser lorsque motion-patterns ne suffit pas.

Quand activer

• Construire des feuilles glisser-pour-fermer, des gestes de glissement ou des listes réorganisables
• Animer du texte mot par mot, caractère par caractère, ou sous forme de 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, suiveur de curseur)
• Ordonnancer des animations multi-étapes de manière impérative avec useAnimate
• Construire des spinners, des squelettes scintillants, des indicateurs d'impulsion ou des états de chargement de boutons

Résultats

Cette compétence produit :

• Interactions de glissement : cartes glissables, feuilles glisser-pour-fermer, listes Reorder.Group
• Hooks de gestes : détection de glissement, appui long, contour de pincement
• Composants d'animation de texte : révélation de mots, 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 useAnimate avec async/await sécurisé contre les interruptions
• Composants de loader : spinner, scintillement, point d'impulsion, 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 + useTransform calcule des valeurs dérivées sans déclencher de re-rendus.
• Les séquences useAnimate sont impératives et sécurisées contre les interruptions — appeler animate() en cours de vol 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

1. Les interactions de glissement doivent être testées sur des appareils tactiles, pas seulement à la souris. La propriété drag fonctionne sur les deux mais la sensation et le seuil diffèrent.
2. 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.
3. Le seuil de glissement doit être explicite. Ne déduisez jamais l'intention uniquement de la vélocité ; combinez les vérifications offset + velocity.
4. La portée scope de useAnimate doit être attachée à un élément DOM monté. Appeler animate() avant le montage échoue silencieusement.
5. Les valeurs de mouvement ne doivent pas être recréées lors du rendu. useMotionValue(0) à l'intérieur du corps d'un composant est correct ; new MotionValue(0) lors d'un rendu ne l'est pas.
6. Toutes les valeurs de tokens sont importées depuis motion-foundations. Pas de nombres en ligne.
7. Les hooks personnalisés doivent gérer le nettoyage. Chaque window.addEventListener a besoin d'un removeEventListener correspondant dans le retour de useEffect.
8. Le morphing SVG nécessite des nombres de commandes de chemin égaux. Les chemins avec des structures de commandes différentes sautent au lieu d'interpoler.

Aide à la décision

Choisir la bonne API avancée

Scénario	API
Glissement avec physique au relâchement	drag + dragTransition: springs.release
Liste ordonnée glisser-pour-réorganiser	Reorder.Group + Reorder.Item
Fermeture sur décalage de glissement	drag="y" + vérification onDragEnd offset
Glissement gauche/droite	drag="x" + vérification onDragEnd offset
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() de motion
Texte entrant mot par mot	Décalage sur les spans inline-block
Dessin SVG	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	Suiveur de curseur, valeurs suivies par le pointeur	Changements d'état discrets
Mises à jour	Continues, à chaque frame	Déclenchées par un changement d'état
Interruption	Douce — la physique reprend à partir de la vélocité	Redémarre à partir de la valeur actuelle

Concepts de base

useMotionValue + useTransform

Calcul réactif sans re-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 re-rendu

useAnimate

Retourne [scope, animate]. La portée scope doit être attachée à un élément DOM. Les appels animate() sont sécurisés contre les interruptions — appeler en cours de vol 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 glissement

"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} />

Suiveur de 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 scintillant

"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 : mettre en pause lorsque l'onglet est caché
    const handleVisibility = () => {
      if (document.visibilityState === "hidden") {
        controls.stop()
      } else {
        pulse()
      }
    }

    pulse()
    document.addEventListener("visibilitychange", handleVisibility)
    return () => {
      controls.stop()
      document.removeEventListener("visibilitychange", handleVisibility)
    }
  }, [controls])

  return (
    <motion.span
      className="inline-block w-3 h-3 rounded-full bg-indigo-500"
      animate={controls}
    />
  )
}