iurymagano/portfolio-next

Plugins GSAP

Quand utiliser cette compétence

À appliquer lors de l'utilisation ou de la révision de code utilisant des plugins GSAP : enregistrement de plugins, scroll-to, animations flip/FLIP, éléments draggable, 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 tweens de base, utiliser gsap-core ; pour ScrollTrigger, utiliser gsap-scrolltrigger ; pour React, utiliser 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 réservés à Club (SplitText, MorphSVG, etc.).

• ✅ Installez tout depuis le package public gsap sur npm : npm install gsap. Tous les plugins sont inclus — importez-les en tant que gsap/SplitText, gsap/MorphSVGPlugin, etc.
• ❌ Ne pas générer de fichier .npmrc avec un jeton d'authentification GreenSock, ni suggérer le registre privé npm.greensock.com, ni 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 l'inclure. Utilisez gsap.registerPlugin() avec tous les plugins utilisés 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 un tween ou un 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 pas enregistrer à l'intérieur d'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éfilant). À utiliser pour "défiler vers un élément" ou "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 un élément)
offsetX, offsetY	Décalage en pixels par rapport à la position cible

ScrollSmoother

Wrapper de défilement lisse (lisse le défilement natif). Nécessite ScrollTrigger et une structure DOM spécifique (wrapper de contenu + wrapper lisse). À utiliser lorsqu'un défilement fluide de type momentum est nécessaire. Voir la documentation GSAP pour la configuration ; enregistrer 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 position: fixed peuvent être placés à 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). À utiliser lors de l'animation entre deux états de mise en page (listes, grilles, développé/réduit).

gsap.registerPlugin(Flip);

const state = Flip.getState(".item");
// modifiez le DOM (réordonnancement, ajout/suppression, changements de classe)
Flip.from(state, { duration: 0.5, ease: "power2.inOut" });

Flip — configuration clé (vars de Flip.from) :

Option	Description
absolute	Utilise 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 les ajuster (évite l'étirement) ; par défaut true
simple	Lorsque vrai, seule la position/l'échelle est animée (plus rapide, moins précis)
duration, ease	Options standard de tween

Plus d'informations

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

Draggable

Rend les éléments glissants, tournables ou jetables avec la souris/le toucher. À utiliser 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 la lancée/le 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 le momentum 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 un simple tween. Enregistrer avec Draggable lors de l'utilisation de inertia: true :

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

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

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

Puis utilisez "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 sur tous les appareils. À utiliser pour les gestes de glissement, la direction de défilement ou la logique de geste personnalisée sans se 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 glissement/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é. À utiliser lors de l'animation de 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). Restaure le balisage d'origine avec revert() ou laissez gsap.context() le faire. S'intègre avec gsap.context(), matchMedia() et useGSAP(). API : SplitText.create(target, vars) (target = 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 et révoquer

Avec onSplit() (v3.13.0+), les animations s'exécutent à chaque division et à chaque re-division lorsque autoSplit est utilisé ; le retour d'un tween/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é (vars de 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 vous n'utilisez pas les lignes) pour les performances. Évitez les caractères seuls 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 finissent de charger 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 dans onSplit() pour qu'elles ciblent les éléments nouvellement divisés ; retournez l'animation depuis onSplit() pour un nettoyage automatique et une synchronisation temporelle lors de la re-division.
onSplit(self)	Callback lorsque la division se termine (et à chaque re-division si autoSplit est true). Reçoit l'instance SplitText. Le retour d'un tween ou d'une timeline GSAP permet l'annulation/la synchronisation automatique de 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 via le tableau masks de l'instance (ou utilisez la classe -mask si une classe est définie).
tag	Balise de l'élément wrapper ; par défaut "div". Utilisez "span" pour l'alignement (note : les transformations comme rotation/scale peuvent ne pas s'afficher sur les éléments en ligne 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 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 un fractionnement personnalisé (par exemple, un joindre de largeur nulle pour les hashtags, ou non latin).
prepareText(text, parent)	Fonction qui reçoit le texte brut et l'élément parent ; retourne le texte modifié avant la division (par exemple pour insérer des marqueurs de rupture pour les langues sans espaces).
propIndex	Lorsque true, ajoute une variable CSS avec un 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 révoquée.

Conseils : Ne divisez que ce qui est animé (par exemple, sautez les caractères si vous n'animez que les mots). 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. À utiliser lors de la révélation ou de la transition de 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 tracé des éléments SVG en animant stroke-dashoffset / stroke-dasharray. Fonctionne sur <path>, <line>, <polyline>, <polygon>, <rect>, <ellipse>. À utiliser lors du "dessin" ou de l'"effacement" de 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). Le tween anime du segment actuel de l'élément au segment cible — par exemple gsap.to("#path", { drawSVG: "0% 100%" }) passe de ce qu'il est actuellement au trait complet. Une valeur unique (par exemple 0, "100%") signifie que le début est 0 : "100%" équivaut à "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 à 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 : Affecte uniquement le trait (pas le remplissage). Privilégiez les éléments <path> à segment unique ; les chemins à segments multiples peuvent s'afficher bizarrement 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 n'ont pas besoin du même nombre de points — MorphSVG les convertit en courbes de Bézier cubiques et ajoute des points si nécessaire. À utiliser pour les transformations d'icône à icône, les transitions de forme ou les animations basées sur un chemin. Fonctionne sur <path>, <polyline> et <polygon> ; <circle>, <rect>, <ellipse> et <line> sont convertis en interne ou via MorphSVGPlugin.convertToPath(selector | element) (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 un polygone/polyline une chaîne de points (par exemple "240,220,240,220") qui sera convertie en données de chemin.

Types d'animation :

• Par défaut, le chemin source se transforme en chemin cible en animant les points.
• Avec shapeIndex: "logical", les points sont réorganisés logiquement pour une transformation plus fluide (souvent meilleure pour les formes de base).
• Avec type: "rotational", l'animation peut inclure une rotation (utile pour les aiguilles d'horloge, etc.).

gsap.registerPlugin(MorphSVGPlugin);

// Transformation simple
gsap.to("#star", {
  duration: 1,
  morphSVG: "#circle"
});

// Avec shapeIndex logique pour une meilleure fluidité
gsap.to("#star", {
  duration: 1,
  morphSVG: { shape: "#circle", shapeIndex: "logical" }
});

En savoir plus : MorphSVG

MotionPath (MotionPathPlugin)

Anime un élément le long d'un chemin SVG. À utiliser pour le mouvement guidé par un chemin (par exemple, un avion suivant une trajectoire de vol).

gsap.registerPlugin(MotionPathPlugin);

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

Physique

Ces plugins permettent des mouvements plus réalistes (ressort, inertie, etc.).

Physics2DPlugin

Applique une vélocité et une accélération 2D à un élément (par exemple, une bale rebondissante, des particules).

gsap.registerPlugin(Physics2DPlugin);

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

PhysicsPropsPlugin

Anime plusieurs propriétés avec une vélocité et une accélération individuelles (par exemple, x, y, rotation).

gsap.registerPlugin(PhysicsPropsPlugin);

gsap.to(".box", {
  physicsProps: {
    x: { velocity: 100, acceleration: 20 },
    rotation: { velocity: 200, acceleration: 0 }
  }
});

Easing

CustomEase

Crée des fonctions d'assouplissement personnalisées à l'aide d'une interface graphique ou en définissant des points de contrôle de Bézier cubique. À utiliser lorsqu'aucun easing intégré ne correspond à l'effet souhaité.

gsap.registerPlugin(CustomEase);

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

EasePack

Fournit des eases supplémentaires :

• easeIn / easeOut / easeInOut pour "rough" (avec des options comme { template: "none", strength: 0.5, points: 20 }), "slow" (pour les eases lents en milieu de mouvement), "expoScale" (pour les eases de mise à l'échelle exponentielles).

gsap.registerPlugin(EasePack);

gsap.to(".box", { duration: 2, ease: "rough({ template: 'none', strength: 0.5 })", x: 500 });

CustomWiggle

Crée un easing d'oscillation personnalisé (va-et-vient comme un ressort).

gsap.registerPlugin(CustomWiggle);

CustomWiggle.create("myWiggle", { wiggles: 6, type: "ease-out" });
gsap.to(".box", { duration: 1, ease: "myWiggle", x: 200 });

CustomBounce

Crée un easing de rebond personnalisé (contrôle du nombre et de l'énergie des rebonds).

gsap.registerPlugin(CustomBounce);

CustomBounce.create("myBounce", { strength: 0.7, squash: 2, squashDuration: 0.2 });
gsap.to(".ball", { duration: 1, ease: "myBounce", y: 300 });

Outils de développement

GSDevTools

Ajoute une interface utilisateur de navigateur avec des commandes de lecture, de pause, de recherche et de visualisation de la chronologie pour le débogage. À utiliser lors du développement d'animations complexes à plusieurs étapes qui bénéficient d'un contrôle visuel.

gsap.registerPlugin(GSDevTools);

const tl = gsap.timeline();
tl.to(".box", { duration: 1, x: 200 })
  .to(".box", { duration: 0.5, rotation: 360 });

GSDevTools.create({ animation: tl });