Motion Avancé

Que fait Motion Avancé ?

Modèles d'animation complexes, interactifs et basés sur la physique. Nécessite d'abord la configuration de motion-foundations. Utilisez-les lorsque motion-patterns ne suffit pas.

Quand l'activer

• Construire des feuilles de glissement 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, transformer des icônes ou animer une progression circulaire
• Écrire un hook d'animation personnalisé (useScrollReveal, bouton magnétique, suiveur de curseur)
• Enchaîner des animations en plusieurs é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

Livrables

Cette compétence produit :

• Interactions de glissement : cartes glissables, feuilles de glissement 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 mots, machine à écrire de caractères, compteur de nombres
• Animation SVG : dessin de chemin, transformation d'icône, anneau de progression de trait
• Hooks personnalisés : useScrollReveal, useHoverScale, useNavigationDirection, useInViewOnce
• Séquences impératives via useAnimate avec async/await interrompable
• Composants de chargement : spinner, scintillement, point d'impulsion, barre de progression, état de chargement de bouton

Principes

• L'animation basée sur la physique (useSpring, springs.*) semble toujours plus naturelle que celle basée 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 interrompables — appeler animate() 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

1. Les interactions de glissement doivent être testées sur les 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 être mises en pause lorsque document.visibilityState === "hidden". Les onglets en arrière-plan ne doivent pas consommer de GPU/CPU.
3. Le seuil de balayage doit être explicite. Ne déduisez jamais l'intention de la seule vélocité ; combinez les vérifications offset + velocity.
4. La référence de portée 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) dans un rendu ne l'est pas.
6. Toutes les valeurs de token sont importées de motion-foundations. Pas de nombres en ligne.
7. Les hooks personnalisés doivent gérer le nettoyage. Chaque window.addEventListener nécessite un removeEventListener correspondant dans le retour du useEffect.
8. La transformation SVG nécessite un nombre égal de commandes de chemin. Les chemins avec des structures de commandes différentes sautent au lieu d'interpoler.

Guide de décision

Choisir l'API avancée approprié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
Rejeter lors du décalage de glissement	drag="y" + vérification du décalage onDragEnd
Balayer à 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 en plusieurs é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	pathLength 0 → 1
Transformation SVG	Interpolation d'attribut d (commandes égales)
Progression circulaire	Interpolation 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 image	Déclenchées par le changement d'état
Interruption	Fluide — 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 image lorsque x change — pas de setState, pas de re-rendu

useAnimate

Renvoie [scope, animate]. La référence de portée doit être attachée à un élément DOM. Les appels animate() sont interrompables — appeler en cours d'exécution annule la précédente exécution.

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 de glissement 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 décalage + vélocité
        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 SEUIL_DECALAGE = 50
const SEUIL_VELOCITE = 300

<motion.div
  drag="x"
  dragConstraints={{ left: 0, right: 0 }}
  onDragEnd={(_, info) => {
    const glisseDroite = info.offset.x > SEUIL_DECALAGE  || info.velocity.x > SEUIL_VELOCITE
    const glisseGauche = info.offset.x < -SEUIL_DECALAGE || info.velocity.x < -SEUIL_VELOCITE
    if (glisseDroite) onSwipeRight()
    if (glisseGauche)  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 de nombres

"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 CIRCONFERENCE = 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={CIRCONFERENCE}
        animate={{ strokeDashoffset: CIRCONFERENCE - (progress / 100) * CIRCONFERENCE }}
        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 du 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 masqué
    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
      className="w-4 h-4 rounded-full bg-indigo-500"
      animate={controls}
    />
  )
}