Dividir en caracteres, palabras y líneas

Animar texto letra a letra parece un problema de animación y en realidad es un problema de manipulación de DOM. Antes de que ningún tween se ejecute hay que convertir un nodo de texto plano en decenas de elementos, cada uno con su caja, su posición y su contribución al layout, sin que el resultado se vea distinto del original ni un píxel. SplitText hace exactamente eso, y conocer la estructura que genera es lo que te permite escribir el CSS que la acompaña en lugar de pelearte con ella.

Tres tipos y su anidamiento

type acepta una lista separada por comas con cualquier combinación de chars, words y lines. El valor por defecto es los tres a la vez, y ese valor por defecto es casi siempre una mala idea: dividir en caracteres un párrafo largo produce centenares de nodos que nunca vas a animar.

La estructura generada se anida en el orden natural. Con type: "lines, words, chars", cada línea contiene palabras y cada palabra contiene caracteres:

<h1 aria-label="Hola mundo">
  <div class="linea" aria-hidden="true">
    <div class="palabra"><div class="letra">H</div><div class="letra">o</div>…</div>
    <div class="palabra"><div class="letra">m</div>…</div>
  </div>
</h1>

Con type: "words" solo hay una capa de palabras. Con type: "chars" solo hay caracteres, y ahí aparece el primer problema real: sin agrupación por palabras, el navegador puede partir una palabra por la mitad al final de una línea, porque cada carácter es una caja independiente y no hay nada que le diga que van juntas. Para eso existe smartWrap: true, que envuelve las palabras en un span con white-space: nowrap. Solo tiene efecto si no estás dividiendo también por palabras o líneas, porque en ese caso la agrupación ya existe.

Los espacios no cuentan como caracteres: no obtendrás un elemento por cada espacio.

import { gsap } from "gsap";
import { SplitText } from "gsap/SplitText";

gsap.registerPlugin(SplitText);

const split = SplitText.create(".titular", { type: "words, chars" });

gsap.from(split.chars, {
  yPercent: 120,
  autoAlpha: 0,
  duration: 0.7,
  ease: "power3.out",
  stagger: 0.02,
});

La instancia expone los resultados en tres arrays: split.chars, split.words y split.lines. Están en orden de documento, así que un stagger sobre ellos recorre el texto de principio a fin. También existe split.masks cuando usas enmascarado, y split.isSplit para saber si la división está aplicada en este momento.

Nombrar lo que se genera

Por defecto los elementos creados no llevan clase, así que la única forma de seleccionarlos es a través de los arrays de la instancia. En cuanto quieras aplicarles CSS —y con líneas casi siempre querrás— hay que nombrarlos.

charsClass, wordsClass y linesClass aceptan un nombre de clase. Y hay un detalle que ahorra mucho código: si terminas el nombre en "++", SplitText añade además una segunda clase numerada empezando en 1.

const split = SplitText.create(".titular", {
  type: "lines, words",
  linesClass: "linea++",   // clase "linea" y ademas "linea1", "linea2", "linea3"...
  wordsClass: "palabra",
});

.linea { overflow: hidden; }
.linea2 { color: var(--acento); }

La alternativa moderna es propIndex: true, que añade a cada elemento una variable CSS con su índice: --char, --word o --line. Eso permite escribir retardos escalonados en CSS puro sin tocar JavaScript, y sobrevive mejor a los cambios porque no depende de generar decenas de clases.

.letra {
  animation: entrar 0.5s both;
  animation-delay: calc(var(--char) * 30ms);
}

tag cambia el elemento contenedor, que por defecto es div. tag: "span" produce marcado más ligero, pero cuidado: los navegadores no aplican transformaciones —rotación, escala, sesgado— a elementos en línea, así que si usas span tendrás que darles display: inline-block en el CSS o las transformaciones no harán nada.

Los casos difíciles

ignore deja sin dividir a los descendientes que le indiques. El caso típico es un sup, un icono en línea o un abbr que se rompería si lo desmontas letra a letra.

SplitText.create(".precio", { type: "chars", ignore: "sup, .icono" });

deepSlice, activado por defecto, resuelve un problema sutil con elementos anidados. Si dentro de tu titular hay un strong que abarca dos líneas y no se subdivide, ese elemento pertenece a dos líneas a la vez y estira una de ellas verticalmente. Con deepSlice, SplitText lo trocea para que cada parte pertenezca a su línea. Solo tiene efecto al dividir por líneas.

wordDelimiter cambia el separador de palabras, que por defecto es el espacio. Sirve para dividir cosas que no tienen espacios, como una etiqueta con varias palabras pegadas: se insertan caracteres invisibles y se declaran como separador. Desde la versión 3.13 acepta además una forma de objeto con una expresión regular y un texto de sustitución.

// Partir #MeEncantaGSAP en palabras usando un juntador de ancho cero
SplitText.create(".hashtag", {
  type: "words",
  wordDelimiter: String.fromCharCode(8205),
});

reduceWhiteSpace, activado por defecto, colapsa los espacios consecutivos igual que hace el navegador. Ponerlo a false los conserva, y desde la 3.13 además inserta br donde hubiera saltos de línea, que es lo que hace falta para dividir el contenido de un pre sin destruir su formato.

prepareText es el escape final: una función que recibe cada bloque de texto crudo y el elemento padre, y devuelve el texto modificado justo antes de que SplitText lo trocee. Es la herramienta para idiomas sin espacios entre palabras, donde hay que insertar los separadores a partir de un análisis propio.

Solo dividir lo que vas a animar

Es la regla más importante y la más ignorada. Cada elemento generado es un nodo del DOM con su propio cálculo de estilo, su propia caja y su propia línea en el árbol de layout. Un párrafo de doscientas palabras dividido en caracteres produce del orden de mil doscientos elementos; cinco párrafos así son seis mil nodos que el navegador tiene que estilar y disponer en cada recálculo.

La consecuencia práctica es que la animación por caracteres pertenece a titulares cortos, y la animación por líneas o por palabras a todo lo demás. Un revelado por líneas sobre un párrafo se ve mejor y cuesta cuarenta veces menos.

// Titular: caracteres, porque son doce
SplitText.create("h1", { type: "chars" });

// Parrafo: lineas, porque son cinco y no cuatrocientas
SplitText.create("p.entradilla", { type: "lines" });