plugins-gsap

Plugins GSAP

Quando Usar Esta Habilidade

Aplique ao usar ou revisar código que utiliza plugins GSAP: registrar plugins, scroll-to, animações flip/FLIP, elementos arrastáveis, SVG (DrawSVG, MorphSVG, MotionPath), texto (SplitText, ScrambleText), física, plugins de easing (CustomEase, EasePack, CustomWiggle, CustomBounce) ou GSDevTools. ScrollTrigger tem sua própria habilidade (gsap-scrolltrigger).

Habilidades relacionadas: Para tweens básicos use gsap-core; para ScrollTrigger use gsap-scrolltrigger; para React use gsap-react.

Licenciamento e Instalação (importante)

Cada plugin GSAP é gratuito, inclusive para uso comercial. Desde a aquisição do GSAP pela Webflow, o Club GSAP não é mais um nível pago e nenhum plugin requer assinatura, chave de licença ou token de autenticação — isso inclui plugins anteriormente exclusivos do Club (SplitText, MorphSVG, etc.).

• ✅ Instale tudo a partir do pacote público gsap no npm: npm install gsap. Todos os plugins estão incluídos — importe-os como gsap/SplitText, gsap/MorphSVGPlugin, etc.
• ❌ Não gere um .npmrc com um token de autenticação GreenSock, sugira o registro privado npm.greensock.com ou diga aos usuários para se inscrever no Club GSAP para acessar um plugin. Essas instruções estão desatualizadas.

Registrando Plugins

Registre cada plugin uma vez para que o GSAP (e os bundlers) saibam que devem incluí-lo. Use gsap.registerPlugin() com todos os plugins usados no projeto:

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

gsap.registerPlugin(ScrollToPlugin, Flip, Draggable);

• ✅ Registre antes de usar o plugin em qualquer tween ou chamada de API.
• ✅ No React, registre no nível superior ou uma vez no aplicativo (por exemplo, antes do primeiro useGSAP); não registre dentro de um componente que renderiza novamente. useGSAP é um plugin que precisa ser registrado antes do uso.

Scroll

ScrollToPlugin

Anima a posição de rolagem (janela ou elemento rolável). Use para "rolar para o elemento" ou "rolar para a posição" sem 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 — configuração chave (objeto scrollTo):

Opção	Descrição
x, y	Posição de rolagem alvo (número) ou "max" para o máximo
element	Seletor ou elemento para rolar até ele (para rolar até a visualização)
offsetX, offsetY	Deslocamento em pixels da posição alvo

ScrollSmoother

Wrapper de rolagem suave (suaviza a rolagem nativa). Requer ScrollTrigger e uma estrutura DOM específica (wrapper de conteúdo + wrapper suave). Use quando for necessária uma rolagem suave com estilo de momentum. Consulte a documentação do GSAP para configuração; registre após o ScrollTrigger. A estrutura DOM seria:

<body>
	<div id="smooth-wrapper">
		<div id="smooth-content">
			<!--- TODO O SEU CONTEÚDO AQUI --->
		</div>
	</div>
	<!-- elementos position: fixed podem ficar fora --->
</body>

DOM / UI

Flip

Capture o estado com Flip.getState(), aplique as alterações (por exemplo, alterações de layout ou classe) e, em seguida, use Flip.from() para animar do estado anterior para o novo estado (FLIP: First, Last, Invert, Play). Use ao animar entre dois estados de layout (listas, grades, expandido/recolhido).

gsap.registerPlugin(Flip);

const state = Flip.getState(".item");
// altere o DOM (reordenar, adicionar/remover, alterar classes)
Flip.from(state, { duration: 0.5, ease: "power2.inOut" });

Flip — configuração chave (vars do Flip.from):

Opção	Descrição
absolute	Use position: absolute durante o flip (padrão: false)
nested	Quando true, apenas o primeiro nível de filhos é medido (melhor para transforms aninhados)
scale	Quando true, escalona os elementos para caber (evita esticar); padrão true
simple	Quando true, apenas posição/escala são animados (mais rápido, menos preciso)
duration, ease	Opções padrão de tween

Mais informações

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

Draggable

Torna elementos arrastáveis, giráveis ou jogáveis com mouse/toque. Use para sliders, cards, listas reordenáveis ou qualquer interação de arrastar.

gsap.registerPlugin(Draggable, InertiaPlugin);

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

Draggable — opções chave de configuração:

Opção	Descrição
type	"x", "y", "x,y", "rotation", "scroll"
bounds	Elemento, seletor ou { minX, maxX, minY, maxY } para restringir o arrasto
inertia	true para habilitar arremesso/momentum (requer InertiaPlugin)
edgeResistance	0–1; resistência ao arrastar além dos limites
cursor	Cursor CSS durante o arrasto
onDragStart, onDrag, onDragEnd	Callbacks; recebem evento e alvo
onThrowUpdate, onThrowComplete	Callbacks quando a inércia está ativa

Inertia (InertiaPlugin)

Funciona com Draggable para momentum após soltar, ou rastreia a inércia/velocidade de qualquer propriedade de qualquer objeto para que possa deslizar suavemente até parar usando um tween simples. Registre com Draggable ao usar inertia: true:

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

Ou rastreie a velocidade de uma propriedade:

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

Em seguida, use "auto" para continuar a velocidade atual e deslizar até parar:

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

Observer

Normaliza a entrada de ponteiro e rolagem entre dispositivos. Use para swipe, direção de rolagem ou lógica de gestos personalizada sem vincular diretamente à posição de rolagem como ScrollTrigger.

gsap.registerPlugin(Observer);

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

Observer — opções chave de configuração:

Opção	Descrição
target	Elemento ou seletor a ser observado
onUp, onDown, onLeft, onRight	Callbacks quando swipe/rolagem ultrapassa a tolerância nessa direção
tolerance	Pixels antes da direção ser detectada; padrão 10
type	"touch", "pointer" ou "wheel" (padrão: "touch,pointer")

Texto

SplitText

Divide o texto de um elemento em caracteres, palavras e/ou linhas (cada um em seu próprio elemento) para animação escalonada ou por unidade. Use ao animar texto caractere por caractere, palavra por palavra ou linha por linha. Retorna uma instância com chars, words, lines (e masks quando mask é definido). Restaure a marcação original com revert() ou deixe gsap.context() reverter. Integra-se com gsap.context(), matchMedia() e useGSAP(). API: SplitText.create(target, vars) (target = seletor, elemento ou array).

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 });
// posteriormente: split.revert() ou deixe gsap.context() limpar reverter

Com onSplit() (v3.13.0+), as animações são executadas em cada divisão e em cada re-divisão quando autoSplit é usado; retornar um tween/timeline de onSplit() permite que SplitText limpe e sincronize o progresso na re-divisão:

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 — configuração chave (vars do SplitText.create):

Opção	Descrição
type	Separado por vírgulas: "chars", "words", "lines". Padrão "chars,words,lines". Divida apenas o necessário (por exemplo, "words, chars" se não usar linhas) para desempenho. Evite chars-only sem palavras/linhas ou use smartWrap: true para evitar quebras de linha estranhas.
charsClass, wordsClass, linesClass	Classe CSS em cada elemento dividido. Acrescente "++" para adicionar uma classe incrementada (por exemplo, linesClass: "line++" → line1, line2, …).
aria	"auto" (padrão), "hidden" ou "none". Acessibilidade: "auto" adiciona aria-label no elemento dividido e aria-hidden nos elementos de linha/palavra/caractere para que leitores de tela leiam o rótulo; "hidden" esconde tudo dos leitores; "none" deixa aria inalterado. Use "none" mais uma duplicata apenas para leitor de tela se links/semântica aninhados precisarem ser expostos.
autoSplit	Quando true, reverte e redivide quando as fontes terminam de carregar ou quando a largura do elemento muda (e as linhas são divididas), evitando quebras de linha incorretas. As animações devem ser criadas dentro de onSplit() para que atinjam os elementos recém-divididos; retorne a animação de onSplit() para limpeza automática e sincronização de tempo na re-divisão.
onSplit(self)	Callback quando a divisão é concluída (e em cada re-divisão se autoSplit for true). Recebe a instância SplitText. Retornar um tween ou timeline GSAP permite reverter/sincronizar automaticamente essa animação ao re-dividir.
mask	"lines", "words" ou "chars". Envolve cada unidade em um elemento extra com overflow: clip para efeitos de máscara/revelação. Apenas um tipo; acesse os wrappers no array masks da instância (ou use a classe -mask se uma classe for definida).
tag	Tag do elemento wrapper; padrão "div". Use "span" para inline (nota: transforms como rotação/escala podem não renderizar em elementos inline em alguns navegadores).
deepSlice	Quando true (padrão), elementos aninhados (por exemplo, <strong>) que abrangem várias linhas são subdivididos para que as linhas não estiquem verticalmente. Aplica-se apenas ao dividir linhas.
ignore	Seletor ou elemento(s) para deixar não divididos (por exemplo, ignore: "sup").
smartWrap	Ao dividir apenas chars, envolve palavras em um span white-space: nowrap para evitar quebras de linha no meio da palavra. Ignorado se palavras ou linhas forem divididas. Padrão false.
wordDelimiter	Limite da palavra: string (padrão " "), RegExp ou { delimiter: RegExp, replaceWith: string } para divisão personalizada (por exemplo, junção de largura zero para hashtags ou não latino).
prepareText(text, parent)	Função que recebe texto bruto e elemento pai; retorna texto modificado antes da divisão (por exemplo, para inserir marcadores de quebra para idiomas sem espaços).
propIndex	Quando true, adiciona uma variável CSS com índice em cada elemento dividido (por exemplo, --word: 1, --char: 2).
reduceWhiteSpace	Recolhe espaços consecutivos; padrão true. A partir da v3.13.0 também respeita quebras de linha e pode inserir <br> para <pre>.
onRevert	Callback quando a instância é revertida.

Dicas: Divida apenas o que é animado (por exemplo, pule chars se estiver animando apenas palavras). Para fontes personalizadas, divida após o carregamento (por exemplo, document.fonts.ready.then(...)) ou use autoSplit: true com onSplit(). Para evitar deslocamento de kerning ao dividir chars, use CSS font-kerning: none; text-rendering: optimizeSpeed;. Evite text-wrap: balance; pode interferir na divisão. SplitText não suporta SVG <text>.

Saiba mais: SplitText

ScrambleText

Anima texto com um efeito de scramble/glitch. Use ao revelar ou fazer transição de texto com um scramble.

gsap.registerPlugin(ScrambleTextPlugin);

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

SVG

DrawSVG (DrawSVGPlugin)

Revela ou esconde o traço de elementos SVG animando stroke-dashoffset / stroke-dasharray. Funciona em <path>, <line>, <polyline>, <polygon>, <rect>, <ellipse>. Use ao "desenhar" ou "apagar" traços.

Valor drawSVG: Descreve o segmento visível do traço ao longo do caminho (posições inicial e final), não "animar de A para B ao longo do tempo." Formato: "start end" em porcentagem ou comprimento. Exemplos: "0% 100%" = traço completo; "20% 80%" = traço apenas entre 20% e 80% (espaços em ambas as extremidades). O tween anima do segmento atual do elemento para o segmento alvo — por exemplo, gsap.to("#path", { drawSVG: "0% 100%" }) vai do que quer que seja agora para o traço completo. Valor único (por exemplo, 0, "100%") significa que o início é 0: "100%" é equivalente a "0% 100%".

Requerido: O elemento deve ter um traço visível — defina stroke e stroke-width em CSS ou como atributos SVG; caso contrário, nada é desenhado.

gsap.registerPlugin(DrawSVGPlugin);

// desenhar do nada ao traço completo
gsap.from("#path", { duration: 1, drawSVG: 0 });
// ou segmento explícito: de 0–0 a 0–100%
gsap.fromTo("#path", { drawSVG: "0% 0%" }, { drawSVG: "0% 100%", duration: 1 });
// traço apenas no meio (espaços nas extremidades)
gsap.to("#path", { duration: 1, drawSVG: "20% 80%" });

Ressalvas: Afeta apenas o traço (não o preenchimento). Prefira elementos <path> de segmento único; caminhos multissegmento podem renderizar de forma estranha em alguns navegadores. O conteúdo de <use> não pode ser alterado visualmente. DrawSVGPlugin.getLength(element) e DrawSVGPlugin.getPosition(element) retornam o comprimento do traço e a posição atual.

Saiba mais: DrawSVG

MorphSVG (MorphSVGPlugin)

Transforma uma forma SVG em outra animando o atributo d (dados do caminho). As formas inicial e final não precisam ter o mesmo número de pontos — MorphSVG converte em curvas Bezier cúbicas e adiciona pontos conforme necessário. Use para morfismos de ícone a ícone, transições de forma ou animações baseadas em caminho. Funciona em <path>, <polyline> e <polygon>; <circle>, <rect>, <ellipse> e <line> são convertidos internamente ou via MorphSVGPlugin.convertToPath(selector | element) (substitui o elemento no DOM por um <path>).

Valor morphSVG: Pode ser um seletor (por exemplo, "#lightning"), um elemento, dados de caminho bruto (por exemplo, "M47.1,0.8 73.3,0.8...") ou, para polígono/polyline, uma string de pontos (por exemplo, "240,220 240,225...").

Configuração chave do MorphSVG:

gsap.to("#star", {
  morphSVG: "#circle",
  duration: 1,
  ease: "power2.inOut"
});

Opções chave:

Opção	Descrição
shapeIndex	Índice da forma alvo (se o alvo tiver várias formas); padrão "auto"
map	"size" (recomendado), "complexity", "clone" ou função personalizada
precompile	Quando true, pré-computa os valores intermediários para desempenho; útil para animações longas ou complexas

Saiba mais: MorphSVG

MotionPath (MotionPathPlugin)

Anima um elemento ao longo de um caminho SVG ou caminho JavaScript. Use para animações de movimento de caminho (por exemplo, objetos seguindo um caminho curvo, animações de trilha, animação de veículos, etc.). Requer um caminho SVG (elemento <path>) ou um array de pontos.

gsap.registerPlugin(MotionPathPlugin);

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

MotionPath — configuração chave:

Opção	Descrição
path	Seletor do elemento <path>, array de pontos [{x, y}], dados de caminho brutos ou um caminho absoluto 2D
align	Alinha o elemento alvo ao caminho; pode ser um seletor, elemento ou true para alinhar ao path
alignOrigin	Ponto de alinhamento no elemento alvo [x%, y%]; padrão [0.5, 0.5] (centro)
autoRotate	Quando true, rotaciona automaticamente o elemento alvo para seguir a direção do caminho; também pode ser um valor [offset, useRadians]
start, end	Posições inicial e final ao longo do caminho (0–1); padrão 0 e 1
resolution	Amostragem de pontos para caminhos não SVG; padrão 20
fromCurrent	Quando true, anima da posição atual do elemento para o caminho
matrix	Transformação de matriz para aplicar ao caminho (útil para animações de eixos)

Saiba mais: MotionPath

Física e Easing

CustomEase

Cria curvas de easing personalizadas desenhando ou fornecendo pontos de controle. Use quando as curvas de easing integradas não forem suficientes.

gsap.registerPlugin(CustomEase);

CustomEase.create("custom", "M0,0 C0.25,0.46 0.45,0.94 1,1");
gsap.to(".box", { x: 500, ease: "custom" });

Configuração chave: Crie uma curva Bezier cúbica com 4 pontos de controle, uma string de caminho SVG ou uma string "easing" do GSAP (por exemplo, "M0,0 C0.25,0.46 0.45,0.94 1,1").

Saiba mais: CustomEase

EasePack

Fornece curvas de easing adicionais como "sine.inOut", "circ.in", "expo.out", "elastic.inOut", "bounce.out", "rough", "slow" e "steps". Elas são úteis para transições mais complexas.

gsap.registerPlugin(EasePack);

gsap.to(".box", { x: 500, duration: 1, ease: "elastic.inOut(1, 0.5)" });
gsap.to(".box2", { x: 500, duration: 1, ease: "rough({strength: 2, points: 20, template: 'none'})" });

Curvas incluídas:

• sine.in, sine.out, sine.inOut
• circ.in, circ.out, circ.inOut
• expo.in, expo.out, expo.inOut
• elastic.in, elastic.out, elastic.inOut (com parâmetros: elastic.inOut(amplitude, period))
• bounce.in, bounce.out, bounce.inOut
• rough (parâmetros: {strength, points, template, taper})
• slow (parâmetros: {linearRatio, power, yoyoMode})
• steps (parâmetros: steps(n))

Saiba mais: EasePack

CustomWiggle

Cria curvas de easing de balanço/wiggle personalizadas para animações de vibração ou oscilação. Use para balançar elementos para frente e para trás com controle preciso.

gsap.registerPlugin(CustomWiggle);

CustomWiggle.create("wiggle1", { wiggles: 8, type: "ease-out" });
gsap.to(".box", { x: 100, ease: "wiggle1", duration: 2 });

Configuração chave:

Opção	Descrição
wiggles	Número de oscilações; padrão 10
type	"ease-out", "ease-in-out" ou "random"

Saiba mais: CustomWiggle

CustomBounce

Cria curvas de easing de bounce personalizadas, substituindo curvas de bounce pré-definidas limitadas por 4 pontos de controle. Use para efeitos de bounce ajustados.

gsap.registerPlugin(CustomBounce);

CustomBounce.create("myBounce", { strength: 0.7, squash: 0.3, endAtEnd: true });
gsap.to(".box", { y: 200, ease: "myBounce", duration: 1 });

Configuração chave:

Opção	Descrição
strength	Força do bounce (0–1); padrão 0.7
squash	Quantidade de squash (0–1); padrão 0.3
endAtEnd	Quando true, termina na posição final (sem oscilações adicionais); padrão true

Saiba mais: CustomBounce

Ferramentas de Desenvolvimento

GSDevTools

Ferramenta visual de linha do tempo para depurar animações GSAP. Fornece controles de reprodução, ajuste de tempo e inspeção de instâncias de animação.

gsap.registerPlugin(GSDevTools);

let tl = gsap.timeline();
tl.to(".box", { x: 100, duration: 1 });
tl.to(".box", { y: 50, duration: 0.5 });
GSDevTools.create({ animation: tl });

Configuração chave:

Opção	Descrição
animation	Timeline ou tween para inspecionar
container	Elemento ou seletor para anexar as ferramentas (padrão: corpo)
position	Posição CSS ("relative", "absolute", etc.)
css	Objeto de estilos CSS para customizar a aparência

Dica: Use gsap.utils.toArray() para iterar e passar várias animações para GSDevTools.

Saiba mais: GSDevTools

Melhores Práticas e Solução de Problemas

1. Registre todos os plugins usados — Sempre use gsap.registerPlugin() com cada plugin antes de instanciar tweens.
2. Importe caminhos corretos — Use caminhos de importação do barrel gsap/ (exemplo: gsap/SplitText, gsap/DrawSVGPlugin). Nunca use registros privados.
3. Precauções de desempenho — Evite registrar plugins múltiplas vezes ou registrar em componentes que renderizam frequentemente (especialmente no React). Prefira registro único no nível superior.
4. Grupos de plugins relacionados — Observações comuns: InertiaPlugin é frequentemente usado com Draggable; GSDevTools é uma ferramenta de depuração, não uma dependência de produção; SplitText e ScrambleText são plugins de texto; DrawSVG e MorphSVG são plugins SVG.
5. Problemas conhecidos — SplitText não funciona com SVG <text>; alguns plugins requerem que o elemento tenha dimensões visíveis; DrawSVG precisa que o elemento tenha um traço definido; MorphSVG pode renderizar de forma estranha em alguns navegadores com caminhos multissegmento.
6. Teste entre navegadores — Alguns efeitos SVG (DrawSVG, MorphSVG) podem variar entre navegadores. Teste no Chrome, Firefox e Safari.
7. Use gsap.context() para limpeza — Especialmente no React ou em ambientes reativos, use gsap.context() para reverter e limpar animações automaticamente.
8. Prefira segmentos de caminho únicos para SVG — Caso contrário, alguns navegadores podem renderizar de forma inconsistente.
9. Separe a lógica de animação da lógica visual — Mantenha as animações focadas no movimento e transições, não na estrutura do DOM.
10. Consulte a documentação oficial — Link para GSAP Plugins para mais exemplos e detalhes.