Vai al contenuto
animorio
EN
Guide

Guida

Come fare un’animazione allo scroll con GSAP e ScrollTrigger

Dalla prima animazione che parte quando un elemento entra nello schermo fino alle sezioni che si fermano mentre il contenuto scorre: come si usano trigger, start, end, scrub e pin, come si aggiunge Lenis per uno scroll morbido e quali sono gli errori che bloccano tutto senza dare un messaggio.

31 ottobre 202611 minuti di letturaIl team di Animorio

Arco dal centroArco dal centro

Un’animazione allo scroll è un’animazione legata alla posizione della pagina invece che al tempo. Ne esistono due famiglie, e conviene distinguerle prima di scrivere una riga di codice. Nella prima lo scroll fa solo da interruttore: quando un elemento entra nello schermo parte un’animazione normale, con la sua durata, e da lì in avanti lo scroll non conta più. Nella seconda lo scroll è la testina di lettura: l’animazione avanza quando la pagina scende e torna indietro quando risale, come se chi legge la tenesse per mano. GSAP con il plugin ScrollTrigger fa tutte e due le cose con la stessa sintassi, ed è lo strumento che usiamo in quasi tutte le animazioni allo scroll della libreria di Animorio.

Preparare la pagina

GSAP e ScrollTrigger si caricano insieme, e il plugin va registrato una volta sola, prima di creare qualunque animazione. Con un bundler si importano da npm; in una pagina semplice bastano due script.

import { gsap } from 'gsap';
import { ScrollTrigger } from 'gsap/ScrollTrigger';

gsap.registerPlugin(ScrollTrigger);

Senza la registrazione ScrollTrigger non dà errori: le animazioni partono subito, tutte insieme, come se lo scroll non esistesse. È il primo controllo da fare quando niente sembra reagire.

La prima animazione: partire quando l’elemento entra

Il caso più comune è far salire un titolo quando arriva nello schermo. Si scrive un tween normale e gli si aggiunge la proprietà scrollTrigger.

gsap.from('.titolo', {
  y: 60,
  opacity: 0,
  duration: 0.9,
  ease: 'power3.out',
  scrollTrigger: {
    trigger: '.titolo',
    start: 'top 85%',
  },
});

La parte da capire è start. Le due parole dicono quale punto dell’elemento deve incontrare quale punto della finestra: top 85% significa che l’animazione parte quando il bordo alto del titolo arriva all’85% dell’altezza dello schermo, cioè poco sopra il fondo. Con top bottom partirebbe appena il titolo spunta, spesso troppo presto perché qualcuno lo veda; con top center partirebbe a metà schermo, quando chi legge ci è già passato sopra con gli occhi. Fra l’80% e il 90% è il punto in cui l’animazione si vede intera.

Per default, se si torna in su, l’animazione resta finita. Se deve ripetersi a ogni passaggio si usa toggleActions, che prende quattro comandi: cosa fare quando si entra scendendo, quando si esce scendendo, quando si rientra salendo e quando si esce salendo. Il valore 'play none none reverse' la fa tornare indietro quando l’elemento esce dal basso, ed è quello che dà la sensazione più naturale nelle liste di schede.

Legare l’animazione allo scroll con scrub

Con scrub l’animazione smette di avere una durata propria: il suo avanzamento diventa la posizione della pagina fra start e end.

gsap.to('.arco', {
  scale: 1,
  ease: 'none',
  scrollTrigger: {
    trigger: '.sezione-arco',
    start: 'top top',
    end: '+=120%',
    scrub: 0.6,
  },
});

Tre dettagli fanno la differenza. Il primo è ease: 'none': quando l’animazione segue lo scroll, una curva in più si sovrappone al movimento della mano e lo rende strano, quindi si lascia lineare e si mette la curva altrove. Il secondo è il valore di scrub: con true l’animazione è attaccata alla barra, con un numero la insegue con quel ritardo in secondi. Un valore fra 0,4 e 1 dà quel leggero ritardo morbido che si vede nell’arco che si apre dal centro allo scroll, dove l’arco cresce un poco dopo la mano. Il terzo è end scritto come '+=120%': vuol dire «finisci dopo aver scrollato il 120% dell’altezza dello schermo da dove sei partito», ed è molto più facile da regolare di un punto assoluto.

Più passi in fila: la timeline

Quando lo scroll deve raccontare più cose, una dopo l’altra, si usa una timeline con un solo ScrollTrigger. Le posizioni dentro la timeline non sono più secondi ma porzioni della distanza di scroll.

const tl = gsap.timeline({
  scrollTrigger: {
    trigger: '.prodotto',
    start: 'top top',
    end: '+=300%',
    scrub: 0.8,
    pin: true,
  },
});

tl.from('.pannello-a', { xPercent: -110 })
  .from('.pannello-b', { yPercent: 110 }, '<0.2')
  .from('.pannello-c', { xPercent: 110 }, '<0.2')
  .to('.cifra', { textContent: 1240, snap: { textContent: 1 } });

Qui la durata totale della timeline viene stirata sui tre schermi di scroll. Se un passo deve durare di più, gli si dà una duration più lunga rispetto agli altri; se serve una pausa, si aggiunge un tween vuoto. È così che è costruita la dashboard che si monta pezzo per pezzo allo scroll: una finestra ferma al centro e i pezzi che entrano ognuno dal suo lato.

Fermare la sezione: pin

Con pin: true ScrollTrigger tiene ferma la sezione per tutta la distanza fra start e end, e aggiunge sotto uno spazio della stessa misura perché il resto della pagina non le salga addosso. È la tecnica delle carte che si impilano e della galleria orizzontale del reportage, dove la pagina si ferma e le foto scorrono di lato.

const fila = document.querySelector('.fila');

gsap.to(fila, {
  x: () => -(fila.scrollWidth - window.innerWidth),
  ease: 'none',
  scrollTrigger: {
    trigger: '.galleria',
    start: 'top top',
    end: () => '+=' + (fila.scrollWidth - window.innerWidth),
    scrub: true,
    pin: true,
    invalidateOnRefresh: true,
  },
});

Le funzioni al posto dei numeri fisse servono per il ridimensionamento: quando la finestra cambia misura ScrollTrigger ricalcola tutto, e con invalidateOnRefresh rilegge anche i valori della fila. Senza, ruotando il telefono la galleria si ferma a metà o scorre oltre la fine.

Il pin ha una regola che vale la pena imparare subito: l’elemento fermato deve essere il contenitore, non un figlio dentro un altro elemento animato. Se un genitore ha già un transform, il position: fixed che ScrollTrigger mette durante il pin si comporta come un absolute e la sezione scappa via. In quei casi si sposta il pin su un elemento più esterno o si usa pinReparent.

Lo scroll morbido con Lenis

Lenis rende lo scroll della rotella morbido, con un’inerzia breve, senza cambiare il modo in cui funziona la pagina: le ancore, la barra e la tastiera restano quelle del browser. Va però collegato a ScrollTrigger, altrimenti i due contano lo scroll in momenti diversi e le animazioni tremano.

import Lenis from 'lenis';

const lenis = new Lenis({ duration: 1.1 });

lenis.on('scroll', ScrollTrigger.update);
gsap.ticker.add((time) => lenis.raf(time * 1000));
gsap.ticker.lagSmoothing(0);

Il ticker di GSAP diventa l’unico orologio: Lenis avanza nello stesso fotogramma in cui GSAP disegna, e ScrollTrigger si aggiorna a ogni passo. lagSmoothing(0) evita che GSAP, dopo un fotogramma lento, salti avanti mentre Lenis no. Sul telefono Lenis per default lascia lo scroll nativo, ed è giusto così: lo scroll del dito è già morbido e un’inerzia in più dà fastidio.

Gli errori che non danno errori

Le animazioni allo scroll si rompono quasi sempre in silenzio. Questi sono i casi che incontriamo più spesso.

once: true su una timeline con ScrollTrigger. Sembra il modo giusto per far partire un’animazione una volta sola, ma su una timeline con ScrollTrigger, aprendo una pagina già scrollata a metà (dopo un ricaricamento o col tasto indietro), può lasciare ScrollTrigger in uno stato in cui nessun altro trigger della pagina si aggiorna. Su un singolo tween o su ScrollTrigger.create va bene; sulle timeline si usano invece i toggleActions o si uccide il trigger a mano nel callback onLeave.

Le misure lette troppo presto. ScrollTrigger calcola le posizioni quando viene creato. Se dopo arriva un’immagine senza width e height, o un carattere che cambia l’altezza dei titoli, tutti i punti di partenza sono sbagliati di qualche centinaio di pixel. Si risolve dando sempre le misure alle immagini e chiamando ScrollTrigger.refresh() quando i caratteri sono pronti, con document.fonts.ready.then(...).

Un elenco vuoto. Se il selettore non trova niente, GSAP avvisa con «target not found» e crea comunque un tween vuoto che allunga la timeline: tutte le animazioni dopo arrivano in ritardo. Prima di animare un elenco conviene controllarne la lunghezza.

Troppi ScrollTrigger. Uno per elemento va bene per una decina di elementi. Su una griglia di trecento schede ogni trigger misura la pagina a ogni ridimensionamento, e il telefono si blocca per secondi. Per gli elenchi lunghi si usa un solo IntersectionObserver che crea l’animazione quando la scheda arriva: ne parliamo nella guida sulle animazioni a 60 fotogrammi al secondo.

Le percentuali nel CSS. GSAP non rilegge i valori in percentuale scritti nel foglio di stile, e il suo transform in linea cancella quello della classe. Se un elemento ha già un translate(-50%, -50%) per stare al centro, GSAP lo perde. La regola che seguiamo è semplice: un elemento per GSAP, il figlio per il CSS, oppure le percentuali passate a GSAP con xPercent e yPercent.

Rispettare chi non vuole il movimento

Chi ha attivato la riduzione del movimento nel sistema non deve vedere sezioni che scorrono di lato o titoli che volano. Con gsap.matchMedia si scrivono due versioni nello stesso posto.

const mm = gsap.matchMedia();

mm.add('(prefers-reduced-motion: no-preference)', () => {
  /* qui le animazioni con pin e scrub */
});

mm.add('(prefers-reduced-motion: reduce)', () => {
  gsap.set('.pannello', { clearProps: 'all' });
});

La versione ridotta non è una pagina vuota: il contenuto deve essere tutto lì, già al suo posto, al massimo con una dissolvenza. Nella guida dedicata alle animazioni accessibili c’è il dettaglio di cosa togliere e cosa tenere.

Da dove partire

Per imparare conviene prendere un esempio che funziona e cambiarne un valore alla volta. Nella libreria ogni pezzo allo scroll ha il Playground con le manopole: si sposta start, si cambia lo scrub, si guarda subito cosa succede, e poi si copia il codice. Il titolo che scopre la foto è un buon esempio di pin con più passi, i numeri che contano e si allargano uno dei casi più semplici di animazione che parte all’ingresso. Partendo da lì, in un pomeriggio si arriva a costruire le proprie sezioni.

Da provare nella libreria

I pezzi citati nella guida, con la demo dal vivo, le manopole e il codice.

Guide