Architecture d'animation GSAP
Référence vérifiée (2026-11-15)
[email protected]est la dernière version sur npm. Son champ licence est "Standard 'no charge' license" (gsap.com/standard-license) : gratuit pour les sites commerciaux, y compris le travail client. La seule utilisation interdite est la création d'outils visuels de construction d'animations sans code qui concurrencent Webflow. Tous les plugins sont livrés dans le package public : ScrollTrigger, ScrollSmoother, SplitText, Flip, Observer, Draggable, InertiaPlugin, CustomEase, CustomBounce, CustomWiggle, MorphSVGPlugin, DrawSVGPlugin, MotionPathPlugin, ScrambleTextPlugin, ScrollToPlugin, Physics2D, PhysicsProps, GSDevTools, et plus encore.@gsap/[email protected]fournituseGSAP.- Re-vérifier avant un nouveau projet :
npm view gsap version licenseetls node_modules/gsap/*.js. - Utiliser ScrollSmoother ou Lenis, jamais les deux. Ce studio standardise sur Lenis (compétence
lenis-scroll).
Architecture (copier assets/ dans src/motion/)
| Fichier | Rôle |
|---|---|
assets/registry.ts | Enregistre les plugins une fois, crée les CustomEases du projet, définit les valeurs par défaut, ScrollTrigger.config({ ignoreMobileResize: true }). Tout importe gsap depuis ici. |
assets/tokens.ts | Jetons de mouvement (durées, eases, staggers) reflétés depuis ANIMATION_SPECIFICATION.md + prefersReducedMotion() |
assets/lit.ts | Exemple de primitive de texte réutilisable : SplitText avec aria:'auto', autoSplit et onSplit retournant le tween. Adapter la révélation à la marque (lit, masqué, glissé…). |
assets/useReducedMotion.ts | Hook en direct pour prefers-reduced-motion afin de basculer au niveau du DOM (ex : afficher des étapes statiques au lieu d'un épingle) |
assets/examples/*.tsx | Motifs testés de la démo de référence : séquence épinglée avec défilement synchronisé (Method), filtre Flip (ScheduleIndex), interaction pilotée par quickTo (TheHour), révélations à vue unique (Rooms), voile de transition de route (Router) |
Ces fichiers sont l'implémentation vérifiée de demo/ dans ce dépôt, testée par sa suite Playwright (nettoyage entre les routes, mouvement réduit, synchronisation du défilement).
Règles qui préviennent 90% des bugs GSAP dans React
- Chaque animation vit à l'intérieur de
useGSAP(() => {...}, { scope: ref }). Le contexte annule tous les tweens, ScrollTriggers, SplitTexts et branches matchMedia lors du démontage. Les animations de gestionnaires d'événements utilisentcontextSafe. - Ne jamais créer de ScrollTriggers à la portée du module ou dans un simple
useEffectsans les annuler. Ne jamais appelerScrollTrigger.killAll()comme stratégie de nettoyage. - Un
gsap.matchMedia()par section avec les conditionsmotion/reduce(et desktop/mobile). Les états cachés initiaux sont définis à l'intérieur de la branche motion, de sorte que les utilisateurs sans JS et avec mouvement réduit voient le contenu final. - Sûr pour le mode strict :
useGSAPgère la double invocation de React 18/19. Vérifier avec un test de fuite :ScrollTrigger.getAll().lengthrevient à la valeur initiale après avoir navigué ailleurs et revenu. - Rafraîchir après les changements de mise en page : après le chargement des polices (
document.fonts.ready.then(() => ScrollTrigger.refresh())), après le filtrage des listes, et après le montage du contenu de la route.invalidateOnRefresh: truesur tout déclencheur dont les valeurs sont calculées à partir de la mise en page. - Épingler correctement : épingler un wrapper intérieur, garder
pinSpacing, lui donner unmin-height: 100svhqui ne dépend pas des polices web, et utiliseranticipatePin: 1avec Lenis. Utiliser un seul épingle par expérience ; les épingles empilées déroutent les utilisateurs. - Animer des propriétés légères : transform, opacity, clip-path ; les variables CSS uniquement sur de petits sous-arbres. Éviter width/height/top/left dans les timelines synchronisées au défilement, et lire la mise en page avant d'écrire (GSAP regroupe ses propres écritures).
will-changeuniquement pendant l'animation, et seulement sur quelques couches.
Recettes
references/recipes.md contient des motifs testés ou documentés pour : séquence héroïque cinématique, révélations SplitText (caractères/mots/lignes, masqués), transitions clip-path et masque, narration épinglée avec défilement, section à défilement horizontal (containerAnimation), couches de parallaxe, morphismes d'état Flip, sections gestuelles pilotées par Observer, carrousels Draggable + Inertia, boutons magnétiques, suiveurs de curseur, morph/dessin SVG, distorsion d'image transmise à WebGL, transitions de page, et défilement 3D avec une caméra WebGL.
references/react-lifecycle.md couvre les changements de route, le redimensionnement, les changements de contenu et le débogage des fuites.
Liste de vérification pour un mouvement intentionnel (avant d'animer)
- Que communique cette animation (hiérarchie, causalité, état, matériau de marque) ? Si rien, supprimez-la.
- Est-ce le moment signature, ou doit-elle rester discrète ?
- Que montre la version à mouvement réduit à la place ? (Elle doit rester parfaitement compréhensible.)
- Quelle est l'expression mobile ? (Les effets de survol nécessitent une alternative tactile ; les épingles sont plus courtes.)
- Combien de ScrollTriggers la page crée-t-elle ? Écrire l'inventaire dans le cahier des charges pour que le QA puisse l'asserter.