Aller au contenu

GSAP : TextPlugin

L'essentiel en 3 points

  1. TextPlugin remplace le texte d'un élément, caractère par caractère : l'effet machine à écrire.
  2. La valeur text peut être un texte simple, ou un objet pour régler le découpage (delimiter), la vitesse (speed) ou une classe CSS (newClass).
  3. Dans votre récit : gardez le texte final dans le HTML, et animez à partir d'un texte vide. Sans animation, le texte reste lisible.

Votre récit doit utiliser au moins une extension de GSAP (autre que ScrollTrigger), au moins une fois par équipe. Choisissez celle qui sert votre histoire.

Ce que ça fait

Démo CodePen : TextPlugin : exemple

Installer

Depuis GSAP 3.13, toutes les extensions sont gratuites, sur le même CDN que GSAP. Si un tutoriel ou une ancienne page parle du « Club GSAP » payant ou de gsap-trial, c'est périmé.

  1. Dans index.html, ajoutez la balise de l'extension après celle de GSAP, et avant main.js :

    <script src="https://cdn.jsdelivr.net/npm/gsap@3.13.0/dist/gsap.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/gsap@3.13.0/dist/TextPlugin.min.js"></script>
<script type="module" src="js/main.js"></script>

  2. Dans main.js, enregistrez-la une fois, avec ScrollTrigger :

    gsap.registerPlugin(ScrollTrigger, TextPlugin);

Comme ScrollTrigger, l'extension est ensuite disponible dans tous vos modules de chapitre, sans import.

Un exemple trouvé ailleurs? Vérifiez sa version

Toutes les démos de cette page sont en GSAP 3. Sur le web, beaucoup d'exemples sont encore en GSAP 2, qui n'est pas entièrement compatible. Comment reconnaître du GSAP 2.

Le principe

TextPlugin remplace le contenu textuel d'un élément, un caractère à la fois. À la fin du tween, le texte a été complètement remplacé. Si on rejoue l'animation à l'envers, le texte revient, lui aussi caractère par caractère.

// Remplace le texte en 2 secondes, à vitesse constante
gsap.to(".narration", {
  duration: 2,
  text: "Ceci est la suite de l'histoire.",
  ease: "none",
});

ease: "none" donne un rythme régulier, comme une machine à écrire.

Démo CodePen : TextPlugin : remplacer un texte

Démo CodePen : TextPlugin : autre exemple

Avec un objet : les options

Pour régler le comportement, text reçoit un objet. Le texte de remplacement va alors dans value.

gsap.to(".narration", {
  duration: 2,
  text: {
    value: "Le loup, lui, l'attendait déjà.",
    delimiter: " ",
  },
});
Option Ce qu'elle fait
value Le texte de remplacement. Obligatoire quand text est un objet.
delimiter Ce qui découpe le texte. Par défaut "" : lettre par lettre. " " : mot par mot. "." : phrase par phrase.
newClass Une classe CSS appliquée au nouveau texte (une couleur, du gras), pour le distinguer de l'ancien.
speed Règle la durée selon la quantité de texte : 1 est lent, 20 est très rapide. Pratique quand vos textes n'ont pas tous la même longueur.

Dans votre récit

Le texte de votre récit doit rester lisible, même sans animation. Écrivez-le dans le HTML (ou dans data.json), et animez à partir d'un texte vide, avec from() :

export function animate(section, chapter) {
  const q = gsap.utils.selector(section);
  const mm = gsap.matchMedia();

  mm.add("(prefers-reduced-motion: no-preference)", () => {
    gsap.from(q(".narration"), {
      text: "",       // part de vide, finit sur le texte du HTML
      duration: 3,
      ease: "none",
      scrollTrigger: {
        trigger: section,
        start: "top 60%",
      },
    });
  });
}

Avec le mouvement réduit, rien ne s'anime : le texte est simplement là.

Un long texte? Pensez speed

Animer 10 caractères en 2 secondes, ou 500, ce n'est pas du tout le même effet. Avec speed, la durée s'ajuste à la longueur du texte.

Références