gsap-plugins

Plugins GSAP

Quand utiliser cette compétence

À utiliser lors de l'utilisation ou de l'examen de code qui utilise des plugins GSAP : enregistrement de plugins, défilement vers un élément, animations flip/FLIP, éléments déplaçables, SVG (DrawSVG, MorphSVG, MotionPath), texte (SplitText, ScrambleText), physique, plugins d'easing (CustomEase, EasePack, CustomWiggle, CustomBounce) ou GSDevTools. ScrollTrigger a sa propre compétence (gsap-scrolltrigger).

Compétences associées : Pour les animations de base, utilisez gsap-core ; pour ScrollTrigger, utilisez gsap-scrolltrigger ; pour React, utilisez gsap-react.

Licence et installation (important)

Chaque plugin GSAP est gratuit, y compris pour un usage commercial. Depuis l'acquisition de GSAP par Webflow, Club GSAP n'est plus un niveau payant et aucun plugin ne nécessite d'adhésion, de clé de licence ou de jeton d'authentification — cela inclut les plugins auparavant exclusifs à Club GSAP (SplitText, MorphSVG, etc.).

• ✅ Installez tout à partir du paquet npm public gsap : npm install gsap. Tous les plugins sont inclus — importez-les comme gsap/SplitText, gsap/MorphSVGPlugin, etc.
• ❌ Ne pas générer de fichier .npmrc avec un jeton d'authentification GreenSock, suggérer le registre privé npm.greensock.com ou dire aux utilisateurs de s'inscrire à Club GSAP pour accéder à un plugin. Ces instructions sont obsolètes.

Enregistrement des plugins

Enregistrez chaque plugin une fois pour que GSAP (et les bundlers) sachent qu'il faut l'inclure. Utilisez gsap.registerPlugin() avec chaque plugin utilisé dans le projet :

import gsap from "gsap";
import { ScrollToPlugin } from "gsap/ScrollToPlugin";
import { Flip } from "gsap/Flip";
import { Draggable } from "gsap/Draggable";

gsap.registerPlugin(ScrollToPlugin, Flip, Draggable);

• ✅ Enregistrez avant d'utiliser le plugin dans toute animation ou appel API.
• ✅ Dans React, enregistrez au niveau supérieur ou une fois dans l'application (par exemple avant la première utilisation de useGSAP) ; ne l'enregistrez pas dans un composant qui se re-rend. useGSAP est un plugin qui doit être enregistré avant utilisation.

Défilement

ScrollToPlugin

Anime la position de défilement (fenêtre ou élément défilable). Utilisez pour « faire défiler vers un élément » ou « faire défiler vers une position » sans ScrollTrigger.

gsap.registerPlugin(ScrollToPlugin);

gsap.to(window, { duration: 1, scrollTo: { y: 500 } });
gsap.to(window, { duration: 1, scrollTo: { y: "#section", offsetY: 50 } });
gsap.to(scrollContainer, { duration: 1, scrollTo: { x: "max" } });

ScrollToPlugin — configuration clé (objet scrollTo) :

Option	Description
x, y	Position de défilement cible (nombre), ou "max" pour le maximum
element	Sélecteur ou élément vers lequel défiler (pour le défilement vers la vue)
offsetX, offsetY	Décalage en pixels par rapport à la position cible

ScrollSmoother

Wrapper de défilement fluide (lisse le défilement natif). Nécessite ScrollTrigger et une structure DOM spécifique (wrapper de contenu + wrapper lisse). Utilisez lorsque un défilement de type momentum est nécessaire. Voir la documentation GSAP pour la configuration ; enregistrez après ScrollTrigger. La structure DOM ressemblerait à :

<body>
	<div id="smooth-wrapper">
		<div id="smooth-content">
			<!--- TOUT VOTRE CONTENU ICI --->
		</div>
	</div>
	<!-- les éléments en position: fixed peuvent aller à l'extérieur --->
</body>

DOM / UI

Flip

Capturez l'état avec Flip.getState(), puis appliquez les modifications (par exemple, changements de mise en page ou de classe), puis utilisez Flip.from() pour animer de l'état précédent au nouvel état (FLIP : First, Last, Invert, Play). Utilisez pour animer entre deux états de mise en page (listes, grilles, développé/réduit).

gsap.registerPlugin(Flip);

const state = Flip.getState(".item");
// modifier le DOM (réorganiser, ajouter/supprimer, changer les classes)
Flip.from(state, { duration: 0.5, ease: "power2.inOut" });

Flip — configuration clé (variables Flip.from) :

Option	Description
absolute	Utiliser position: absolute pendant le flip (par défaut : false)
nested	Lorsque vrai, seul le premier niveau d'enfants est mesuré (meilleur pour les transformations imbriquées)
scale	Lorsque vrai, met à l'échelle les éléments pour qu'ils s'adaptent (évite l'étirement) ; par défaut true
simple	Lorsque vrai, seules la position/l'échelle sont animées (plus rapide, moins précis)
duration, ease	Options d'animation standard

Plus d'informations

https://gsap.com/docs/v3/Plugins/Flip

Draggable

Rend les éléments déplaçables, rotatifs ou « jetables » avec la souris/le toucher. Utilisez pour les curseurs, les cartes, les listes réorganisables ou toute interaction de glissement.

gsap.registerPlugin(Draggable, InertiaPlugin);

Draggable.create(".box", { type: "x,y", bounds: "#container", inertia: true });
Draggable.create(".knob", { type: "rotation" });

Draggable — options de configuration clés :

Option	Description
type	"x", "y", "x,y", "rotation", "scroll"
bounds	Élément, sélecteur ou { minX, maxX, minY, maxY } pour contraindre le glissement
inertia	true pour activer le lancer/momentum (nécessite InertiaPlugin)
edgeResistance	0–1 ; résistance lors du glissement au-delà des limites
cursor	Curseur CSS pendant le glissement
onDragStart, onDrag, onDragEnd	Callbacks ; reçoivent l'événement et la cible
onThrowUpdate, onThrowComplete	Callbacks lorsque l'inertie est active

Inertia (InertiaPlugin)

Fonctionne avec Draggable pour l'élan après le relâchement, ou suit l'inertie/la vélocité de toute propriété de tout objet afin qu'elle puisse ensuite glisser parfaitement jusqu'à l'arrêt en utilisant une simple animation. Enregistrez avec Draggable lors de l'utilisation de inertia: true :

gsap.registerPlugin(Draggable, InertiaPlugin);
Draggable.create(".box", { type: "x,y", inertia: true });

Ou suivez la vélocité d'une propriété :

InertiaPlugin.track(".box", "x");

Utilisez ensuite "auto" pour continuer la vélocité actuelle et glisser jusqu'à l'arrêt :

gsap.to(obj, { inertia: { x: "auto" } });

Observer

Normalise les entrées de pointeur et de défilement entre les appareils. Utilisez pour le balayage, la direction de défilement ou la logique de gestes personnalisée sans lier directement à la position de défilement comme ScrollTrigger.

gsap.registerPlugin(Observer);

Observer.create({
  target: "#area",
  onUp: () => {},
  onDown: () => {},
  onLeft: () => {},
  onRight: () => {},
  tolerance: 10
});

Observer — options de configuration clés :

Option	Description
target	Élément ou sélecteur à observer
onUp, onDown, onLeft, onRight	Callbacks lorsque le balayage/le défilement dépasse la tolérance dans cette direction
tolerance	Pixels avant que la direction ne soit détectée ; par défaut 10
type	"touch", "pointer" ou "wheel" (par défaut : "touch,pointer")

Texte

SplitText

Divise le texte d'un élément en caractères, mots et/ou lignes (chacun dans son propre élément) pour une animation en décalé ou par unité. Utilisez pour animer du texte caractère par caractère, mot par mot ou ligne par ligne. Renvoie une instance avec chars, words, lines (et masks lorsque mask est défini). Restaurez le balisage original avec revert() ou laissez gsap.context() le rétablir. S'intègre avec gsap.context(), matchMedia() et useGSAP(). API : SplitText.create(target, vars) (cible = sélecteur, élément ou tableau).

gsap.registerPlugin(SplitText);

const split = SplitText.create(".heading", { type: "words, chars" });
gsap.from(split.chars, { opacity: 0, y: 20, stagger: 0.03, duration: 0.4 });
// plus tard : split.revert() ou laissez gsap.context() nettoyer / rétablir

Avec onSplit() (v3.13.0+), les animations s'exécutent sur chaque division et lors d'une re-division lorsque autoSplit est utilisé ; le renvoi d'une animation/timeline depuis onSplit() permet à SplitText de nettoyer et de synchroniser la progression lors de la re-division :

SplitText.create(".split", {
  type: "lines",
  autoSplit: true,
  onSplit(self) {
    return gsap.from(self.lines, { y: 100, opacity: 0, stagger: 0.05, duration: 0.5 });
  }
});

SplitText — configuration clé (variables SplitText.create) :

Option	Description
type	Séparé par des virgules : "chars", "words", "lines". Par défaut "chars,words,lines". Ne divisez que ce qui est nécessaire (par exemple "words, chars" si les lignes ne sont pas utilisées) pour les performances. Évitez chars uniquement sans mots/lignes ou utilisez smartWrap: true pour éviter les sauts de ligne étranges.
charsClass, wordsClass, linesClass	Classe CSS sur chaque élément divisé. Ajoutez "++" pour ajouter une classe incrémentée (par exemple linesClass: "line++" → line1, line2, …).
aria	"auto" (par défaut), "hidden" ou "none". Accessibilité : "auto" ajoute aria-label sur l'élément divisé et aria-hidden sur les éléments de ligne/mot/caractère afin que les lecteurs d'écran lisent l'étiquette ; "hidden" cache tout aux lecteurs ; "none" laisse aria inchangé. Utilisez "none" plus un doublon réservé aux lecteurs d'écran si des liens/sémantiques imbriqués doivent être exposés.
autoSplit	Lorsque true, annule et re-divise lorsque les polices sont chargées ou lorsque la largeur de l'élément change (et que les lignes sont divisées), évitant les sauts de ligne incorrects. Les animations doivent être créées à l'intérieur de onSplit() afin qu'elles ciblent les éléments nouvellement divisés ; renvoyez l'animation depuis onSplit() pour un nettoyage automatique et une synchronisation temporelle lors de la re-division.
onSplit(self)	Callback lorsque la division est terminée (et lors de chaque re-division si autoSplit est true). Reçoit l'instance SplitText. Renvoyer une animation ou timeline GSAP permet d'annuler/synchroniser automatiquement cette animation lors de la re-division.
mask	"lines", "words" ou "chars". Enveloppe chaque unité dans un élément supplémentaire avec overflow: clip pour les effets de masque/révélation. Un seul type ; accédez aux wrappers sur le tableau masks de l'instance (ou utilisez la classe -mask si une classe est définie).
tag	Balise d'élément wrapper ; par défaut "div". Utilisez "span" pour inline (note : les transformations comme la rotation/l'échelle peuvent ne pas s'afficher sur les éléments inline dans certains navigateurs).
deepSlice	Lorsque true (par défaut), les éléments imbriqués (par exemple <strong>) qui s'étendent sur plusieurs lignes sont subdivisés afin que les lignes ne s'étirent pas verticalement. S'applique uniquement lors de la division des lignes.
ignore	Sélecteur ou élément(s) à laisser non divisés (par exemple ignore: "sup").
smartWrap	Lors de la division des chars uniquement, enveloppe les mots dans un span white-space: nowrap pour éviter les sauts de ligne au milieu des mots. Ignoré si les mots ou les lignes sont divisés. Par défaut false.
wordDelimiter	Limite de mot : chaîne (par défaut " "), RegExp, ou { delimiter: RegExp, replaceWith: string } pour une division personnalisée (par exemple, joncteur de largeur nulle pour les hashtags, ou non latin).
prepareText(text, parent)	Fonction qui reçoit le texte brut et l'élément parent ; renvoie le texte modifié avant la division (par exemple, pour insérer des marqueurs de saut pour les langues sans espaces).
propIndex	Lorsque true, ajoute une variable CSS avec l'index sur chaque élément divisé (par exemple --word: 1, --char: 2).
reduceWhiteSpace	Réduit les espaces consécutifs ; par défaut true. Depuis la v3.13.0, respecte également les sauts de ligne et peut insérer <br> pour <pre>.
onRevert	Callback lorsque l'instance est annulée.

Conseils : Ne divisez que ce qui est animé (par exemple, ignorez les caractères si seuls les mots sont animés). Pour les polices personnalisées, divisez après leur chargement (par exemple document.fonts.ready.then(...)) ou utilisez autoSplit: true avec onSplit(). Pour éviter le décalage de crénage lors de la division des caractères, utilisez CSS font-kerning: none; text-rendering: optimizeSpeed;. Évitez text-wrap: balance ; cela peut interférer avec la division. SplitText ne prend pas en charge le texte SVG <text>.

En savoir plus : SplitText

ScrambleText

Anime le texte avec un effet de brouillage/glitch. Utilisez pour révéler ou transitionner du texte avec un brouillage.

gsap.registerPlugin(ScrambleTextPlugin);

gsap.to(".text", {
  duration: 1,
  scrambleText: { text: "Nouveau message", chars: "01", revealDelay: 0.5 }
});

SVG

DrawSVG (DrawSVGPlugin)

Révèle ou masque le trait des éléments SVG en animant stroke-dashoffset / stroke-dasharray. Fonctionne sur <path>, <line>, <polyline>, <polygon>, <rect>, <ellipse>. Utilisez pour « dessiner » ou « effacer » des traits.

Valeur drawSVG : Décrit le segment visible du trait le long du chemin (positions de début et de fin), pas « animer de A à B dans le temps ». Format : "début fin" en pourcentage ou en longueur. Exemples : "0% 100%" = trait complet ; "20% 80%" = trait uniquement entre 20 % et 80 % (espaces aux deux extrémités). L'animation anime du segment actuel de l'élément au segment cible — par exemple gsap.to("#path", { drawSVG: "0% 100%" }) va de ce qu'il est maintenant au trait complet. Une seule valeur (par exemple 0, "100%") signifie que le début est 0 : "100%" est équivalent à "0% 100%".

Requis : L'élément doit avoir un trait visible — définissez stroke et stroke-width en CSS ou comme attributs SVG ; sinon, rien n'est dessiné.

gsap.registerPlugin(DrawSVGPlugin);

// dessiner de rien au trait complet
gsap.from("#path", { duration: 1, drawSVG: 0 });
// ou segment explicite : de 0–0 à 0–100 %
gsap.fromTo("#path", { drawSVG: "0% 0%" }, { drawSVG: "0% 100%", duration: 1 });
// trait uniquement au milieu (espaces aux extrémités)
gsap.to("#path", { duration: 1, drawSVG: "20% 80%" });

Mises en garde : N'affecte que le trait (pas le remplissage). Préférez les éléments <path> à segment unique ; les chemins multi-segments peuvent rendre étrangement dans certains navigateurs. Le contenu de <use> ne peut pas être modifié visuellement. DrawSVGPlugin.getLength(element) et DrawSVGPlugin.getPosition(element) renvoient la longueur du trait et la position actuelle.

En savoir plus : DrawSVG

MorphSVG (MorphSVGPlugin)

Transforme une forme SVG en une autre en animant l'attribut d (données de chemin). Les formes de début et de fin ne doivent pas avoir le même nombre de points — MorphSVG convertit en courbes de Bézier cubiques et ajoute des points si nécessaire. Utilisez pour les transformations d'icône en icône, les transitions de forme ou les animations basées sur le chemin. Fonctionne sur <path>, <polyline> et <polygon> ; <circle>, <rect>, <ellipse> et <line> sont convertis en interne ou via MorphSVGPlugin.convertToPath(sélecteur | élément) (remplace l'élément dans le DOM par un <path>).

Valeur morphSVG : Peut être un sélecteur (par exemple "#lightning"), un élément, des données de chemin brutes (par exemple "M47.1,0.8 73.3,0.8...") ou, pour polygon/polyline, une chaîne de points (par exemple "240,220 240,240..."). Objet pour des options avancées :

• { shape: "#target" } ou { shape: "une chaîne de données de chemin" }
• { shape: "#target", useAbsolutePosition: true } pour préserver la position de l'élément
• { shape: "#target", rotation: 90, scale: 0.5 } (rotation/échelle sans affecter la position)
• { shapeIndex: 2 } pour cibler un sous-chemin spécifique dans une forme multi-chemins

Propriétés sur l'instance de morphing :

Propriété	Description
fromData, toData	Données de chemin de début et de fin après conversion (forme normalisée)
fromPoint, toPoint	Tableaux de points des courbes pour les deux formes

gsap.registerPlugin(MorphSVGPlugin);

// transformation simple
MorphSVGPlugin.convertToPath("ellipse, circle"); // convertir d'abord si nécessaire
gsap.to("#moon", { morphSVG: "#sun", duration: 1 });
// avec position absolue
gsap.to("#moon", { morphSVG: { shape: "#sun", useAbsolutePosition: true }, duration: 1 });
// cibler l'index de sous-chemin
gsap.to("#multiPathShape", { morphSVG: { shape: "#target", shapeIndex: 1 } });

Désactiver la synchronisation du déclenchement (pour le remplissage de ligne/barre) :

MorphSVGPlugin.defaultRender = "lineFill";

En savoir plus : MorphSVG

MotionPath (MotionPathPlugin)

Anime un élément le long d'un chemin SVG. Utilisez pour les animations de mouvement le long d'une trajectoire définie.

gsap.registerPlugin(MotionPathPlugin);

gsap.to("#plane", {
  motionPath: {
    path: "#flightPath",
    align: "#flightPath",
    alignOrigin: [0.5, 0.5],
    autoRotate: true
  },
  duration: 3
});

MotionPath — options clés :

Option	Description
path	Chemin (sélecteur, élément SVG ou tableau de points [{x, y}])
align	Élément ou sélecteur sur lequel aligner l'élément animé
alignOrigin	[x, y] sur l'élément animé à aligner sur le chemin (par défaut [0.5, 0.5])
autoRotate	Lorsque true, fait pivoter l'élément pour qu'il suive la tangente du chemin
start, end	0–1, section du chemin à utiliser (par défaut 0, 1)

En savoir plus : MotionPath

Physique

Physics2D (Physics2DPlugin)

Anime un élément avec une vélocité, une accélération et une gravité simulées. Utilisez pour des mouvements physiques réalistes comme lancer, sauter ou des trajectoires.

gsap.registerPlugin(Physics2DPlugin);

gsap.to("#ball", {
  physics2D: {
    velocity: 400,
    angle: 45,
    gravity: 300
  },
  duration: 2
});

Physics2D — options clés :

Option	Description
velocity	Vélocité initiale en pixels par seconde
angle	Angle du mouvement en degrés (0 = droite, 90 = haut)
gravity	Accélération gravitationnelle directionnelle en pixels/s² (négatif = haut)
acceleration	Accélération supplémentaire en pixels/s²
friction	Coefficient de frottement (0–1) qui ralentit le mouvement

PhysicsProps (PhysicsPropsPlugin)

Applique une physique indépendante aux propriétés de style CSS individuelles. Utilisez pour des effets physiques par propriété comme rebondir, osciller ou amortir.

gsap.registerPlugin(PhysicsPropsPlugin);

gsap.to("#box", {
  physicsProps: {
    x: { velocity: 500, spring: 200 },
    rotation: { velocity: 300, friction: 0.5 }
  },
  duration: 2
});

PhysicsProps — options pour chaque propriété :

Option	Description
velocity	Vélocité initiale de la propriété
acceleration	Accélération constante de la propriété
friction	Coefficient de frottement (0–1)
spring	Raideur du ressort (plus élevé = oscillations plus rapides)
damping	Amortissement du ressort (0–1 ; 1 = pas d'oscillation)

Easing personnalisé

CustomEase

Crée un easing personnalisé avec un chemin de Bézier cubique (en forme de M0,0 C...). Utilisez pour des effets d'easing uniques non disponibles dans les easings intégrés.

gsap.registerPlugin(CustomEase);

CustomEase.create("myEase", "M0,0 C0.25,0.1 0.25,1 1,1");
gsap.to(".box", { duration: 1, ease: "myEase" });

Création avec le générateur visuel :

CustomEase.create("cubic", "M0,0 C0.25,0.46 0.45,0.94 1,1");

EasePack

Easings additifs : SlowMo, SteppedEase, RoughEase, ExpoScaleEase. Utilisez pour des comportements d'easing spécialisés comme le ralenti, le stepping ou les sequences brutes.

gsap.registerPlugin(EasePack);

// SlowMo : ralenti au début/à la fin
gsap.to(".box", {
  duration: 2,
  ease: "slowMo(0.5, 0.7)"
});

// SteppedEase : animation discrète par pas
gsap.to(".box", {
  duration: 2,
  ease: "steps(10)"
});

// RoughEase : ajoute des secousses aléatoires
gsap.to(".box", {
  duration: 2,
  ease: "rough({strength: 0.5, points: 20})"
});

// ExpoScaleEase : mise à l'échelle avec base d'exposant personnalisée
gsap.to(".box", {
  duration: 2,
  ease: "expoScale(2, 10)"
});

CustomWiggle

Crée un easing d'oscillation personnalisé avec des paramètres de fréquence, d'amortissement et de type d'onde. Utilisez pour les effets de rebond/oscillation.

gsap.registerPlugin(CustomWiggle);

CustomWiggle.create("myWiggle", { wiggles: 6, type: "ease-in-out", amplitude: 0.5 });
gsap.to(".box", { duration: 1.5, ease: "myWiggle" });

CustomWiggle — options clés :

Option	Description
wiggles	Nombre de cycles d'oscillation (par défaut 10)
type	"ease-in-out", "ease-in", "ease-out" ou "anticipate"
amplitude	Amplitude initiale (1 = pleine ; par défaut 0.5)

CustomBounce

Crée un easing de rebond personnalisé avec des paramètres de force et de nombre. Utilisez pour des effets de rebond configurables.

gsap.registerPlugin(CustomBounce);

CustomBounce.create("myBounce", { strength: 0.7, bounce: 4 });
gsap.to(".box", { duration: 1, ease: "myBounce" });

CustomBounce — options clés :

Option	Description
strength	Force du premier rebond (0–1 ; par défaut 0.7)
bounce	Nombre de rebonds (par défaut 4)

Débogage et développement

GSDevTools

Ajoute une interface visuelle pour contrôler et inspecter les animations GSAP. Utilisez pour le débogage : pause/lecture, défilement temporel, ajustement de la vitesse et visualisation du déroulement.

this.control = GSDevTools.create({ animation: mainTimeline });

GSDevTools — options clés :

Option	Description
animation	Animation ou timeline à contrôler (obligatoire)
container	Élément ou sélecteur dans lequel injecter l'interface
css	Objet de styles CSS pour personnaliser l'interface
id	Identifiant de l'instance pour les références programmatiques

En savoir plus : GSDevTools