iurymagano/portfolio-next

Plugins GSAP

Quando Usar Este Skill

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 seu próprio skill (gsap-scrolltrigger).

Skills relacionados: 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 exige assinatura, chave de licença ou token de autenticação — isso inclui plugins que antes eram exclusivos do Club (SplitText, MorphSVG, etc.).

• ✅ Instale tudo a partir do pacote npm público gsap: 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, não sugira o registro privado npm.greensock.com e não diga aos usuários para se inscreverem no Club GSAP para acessar um plugin. Essas instruções estão desatualizadas.

Registro de Plugins

Registre cada plugin uma vez para que o GSAP (e os bundlers) saibam 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 um elemento rolável). Use para "rolar até o elemento" ou "rolar até 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(containerRolagem, { 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 vista)
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. Veja a documentação do GSAP para configuração; registre após o ScrollTrigger. A estrutura DOM seria assim:

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

DOM / UI

Flip

Capture o estado com Flip.getState(), aplique alterações (por exemplo, layout ou mudanças de classe), então 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 verdadeiro, apenas o primeiro nível de filhos é medido (melhor para transformações aninhadas)
scale	Quando verdadeiro, dimensiona os elementos para caber (evita esticar); padrão true
simple	Quando verdadeiro, 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 lançáveis com mouse/toque. Use para sliders, cartões, 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 ativar lançamento/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 a soltura, ou rastreia a inércia/velocidade de qualquer propriedade de qualquer objeto para que ela 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 deslizar, 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 observar
onUp, onDown, onLeft, onRight	Callbacks quando um deslize/rolagem ultrapassa a tolerância naquela 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 está 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) (alvo = 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 });
// depois: split.revert() ou deixe gsap.context() limpar e reverter

Com onSplit() (v3.13.0+), as animações são executadas em cada divisão e em cada redivisão quando autoSplit é usado; retornar um tween/timeline de onSplit() permite que SplitText limpe e sincronize o progresso na redivisã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írgula: "chars", "words", "lines". Padrão "chars,words,lines". Divida apenas o necessário (ex.: "words, chars" se não estiver usando linhas) para performance. Evite apenas chars sem words/lines ou use smartWrap: true para evitar quebras de linha estranhas.
charsClass, wordsClass, linesClass	Classe CSS em cada elemento dividido. Anexe "++" para adicionar uma classe incrementada (ex.: 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" oculta 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 redivida quando as fontes terminarem de carregar ou quando a largura do elemento mudar (e as linhas forem 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 redivisão.
onSplit(self)	Callback quando a divisão é concluída (e em cada redivisão se autoSplit for true). Recebe a instância SplitText. Retornar um tween ou timeline GSAP permite reversão/sincronização automática dessa animação ao redividir.
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 classe -mask se uma classe for definida).
tag	Tag do elemento wrapper; padrão "div". Use "span" para inline (nota: transformações como rotação/escala podem não renderizar em elementos inline em alguns navegadores).
deepSlice	Quando true (padrão), elementos aninhados (ex.: <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) a deixar não divididos (ex.: 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 de palavra: string (padrão " "), RegExp, ou { delimiter: RegExp, replaceWith: string } para divisão personalizada (ex.: junção de largura zero para hashtags, ou não latino).
prepareText(text, parent)	Função que recebe o texto bruto e o elemento pai; retorna o texto modificado antes da divisão (ex.: para inserir marcadores de quebra para idiomas sem espaços).
propIndex	Quando true, adiciona uma variável CSS com índice em cada elemento dividido (ex.: --word: 1, --char: 2).
reduceWhiteSpace	Colapsa 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 (ex.: pule chars se estiver animando apenas palavras). Para fontes personalizadas, divida após o carregamento (ex.: 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 embaralhamento/glitch. Use ao revelar ou fazer transição de texto com um embaralhamento.

gsap.registerPlugin(ScrambleTextPlugin);

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

SVG

DrawSVG (DrawSVGPlugin)

Revela ou oculta 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: "inicio fim" 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 — ex.: gsap.to("#path", { drawSVG: "0% 100%" }) vai do que quer que seja agora para o traço completo. Valor único (ex.: 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 no CSS ou como atributos SVG; caso contrário, nada será 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 com vários segmentos 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 de Bézier cúbicas e adiciona pontos conforme necessário. Use para transformações de ícone para í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 (ex.: "#lightning"), um elemento, dados de caminho brutos (ex.: "M47.1,0.8 73.3,0.8..."), ou para polygon/polyline uma string de pontos (ex.: "240,220 240,...").

shapeIndex permite selecionar qual sub-caminho almejar quando o alvo ou elemento tem múltiplos sub-caminhos (ex.: shapeIndex: 2).

MorphSVGPlugin.convertToPath(target) converte o alvo em um caminho e retorna o(s) elemento(s) <path> resultantes. Aceita seletor, elemento ou NodeList.

Dica: Anime subtamente com gsap.to() em vez de gsap.from() para melhores resultados. Se o início e o fim parecerem distorcidos, use type: "rotational" ou type: "linear" .

Saiba mais: MorphSVG

MotionPath (MotionPathPlugin)

Anima um elemento ao longo de um caminho SVG ou caminho de coordenadas. Use quando um elemento deve se mover ao longo de uma trajetória (não apenas desenhar o traço).

gsap.registerPlugin(MotionPathPlugin);

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

MotionPath — opções chave:

Opção	Descrição
path	Caminho SVG (seletor), array de pontos [{x, y}, ...], ou string de dados de caminho
align	Elemento ou seletor no qual alinhar o elemento alvo
alignOrigin	[x, y] (0–1) ponto de origem do alinhamento no elemento alvo; padrão [0.5, 0.5] (centro)
autoRotate	Quando true, rotaciona o elemento para seguir a direção do caminho
start	Posição inicial ao longo do caminho (0–1); padrão 0
end	Posição final ao longo do caminho (0–1); padrão 1
curviness	Quantidade de curvatura para caminhos com pontos; padrão 1 (1 = curvas suaves)
type	"cubic" (curvas suaves) ou "thru" (passa exatamente por cada ponto); padrão "cubic"
useRadians	Se true, usa radianos em vez de graus para o ângulo; padrão false
resolution	Número de pontos por curva; padrão 20 (maior = mais preciso)

Física e Easing

Physics2D (Physics2DPlugin)

Simula física 2D (velocidade, aceleração, ângulo, gravidade). Use para animações de projéteis, partículas ou movimentos físicos.

gsap.registerPlugin(Physics2DPlugin);

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

PhysicsProps (PhysicsPropsPlugin)

Aplica aceleração/velocidade baseada em física a propriedades arbitrárias de um objeto (útil para múltiplas propriedades com física independente).

gsap.registerPlugin(PhysicsPropsPlugin);

gsap.to(obj, {
  physicsProps: {
    x: { velocity: 100, acceleration: 50 },
    y: { velocity: -50, acceleration: -100 }
  }
});

CustomEase

Cria funções de easing personalizadas com um editor visual ou array de pontos. Use quando o easing integrado não for suficiente. Não precisa de registro, apenas importação.

import { CustomEase } from "gsap/CustomEase";

CustomEase.create("minhaEasing", "M0,0 C0.2,0.8 0.6,1 1,1");
gsap.to(".box", { duration: 1, ease: "minhaEasing", x: 500 });

EasePack

Easings adicionais: Sine, Circ, Expo, Elastic, Back, Bounce, SlowMo, SteppedEase, RoughEase (estes são easings especiais), ExpoScaleEase. Registre apenas se usar o EasePack como pacote; normalmente as easings são acessadas por string (ex.: "sine.inOut").

gsap.registerPlugin(EasePack);

CustomWiggle

Cria um easing que balança (vibra) com uma configuração personalizada. Use para animações de tremor, vibração ou oscilação.

import { CustomWiggle } from "gsap/CustomWiggle";

CustomWiggle.create("tremor", { wiggles: 6, type: "easeOut" });
gsap.to(".box", { duration: 1, ease: "tremor", x: 30 });

CustomBounce

Cria um easing de quique personalizado com controle sobre o número de quiques, força e elasticidade.

import { CustomBounce } from "gsap/CustomBounce";

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

GSDevTools

Adiciona uma interface de controle (play/pause, scrub, seek) para animações. Use para depuração e preferências do usuário.

gsap.registerPlugin(GSDevTools);

const tl = gsap.timeline();
tl.to(".box", { x: 300, duration: 2 });
GSDevTools.create({ animation: tl });

GSDevTools — opções chave:

Opção	Descrição
animation	Tween ou timeline a ser controlada por esta ferramenta
container	Container do seletor ou elemento onde renderizar a IU; padrão "#GSDevTools"
css	Caminho para CSS personalizado; se fornecido, ignora o padrão
id	ID para esta instância (útil para múltiplas ferramentas)

Saiba Mais

• Documentação completa do GSAP: https://gsap.com/docs/v3/
• Todos os plugins: https://gsap.com/docs/v3/Plugins/
• Guia de instalação: https://gsap.com/resources/Installation