@thecoderzeus/scroll-reveal-fx

v1.1.2

Published

4 months ago

Uma suíte de animação de alta performance, modular e sem dependências, para criar interações ricas e elegantes baseadas no scroll e no mouse.

0High
0Medium
0Low

thecoderzeus

scroll reveal animation effects scroll-reveal parallax svg-animation text-animation intersection-observer timeline scrub react nextjs typescript

@thecoderzeus/scroll-reveal-fx

Uma suíte de animação de alta performance, modular e sem dependências, para criar interações ricas e elegantes baseadas no scroll e no mouse.

Features

Animação de Revelação: Efeitos de fade, slide, scale, blur, flip, rotate, roll e flicker.
Animação de Texto Avançada: Modos de typewriter, ordem aleatória e múltiplos efeitos.
Animação de SVG: Efeito de desenho de SVGs.
Animação Scrub: Vincule o progresso de uma animação diretamente à posição do scroll.
Engine de Timeline: Orquestre sequências de animações complexas com facilidade.
Efeitos de Mouse: Adicione interatividade com efeitos como tilt.
Efeito Parallax: Crie uma ilusão de profundidade com scroll.
Gatilhos e Callbacks: Controle preciso sobre quando e como as animações acontecem.

Installation

npm install @thecoderzeus/scroll-reveal-fx
# ou
yarn add @thecoderzeus/scroll-reveal-fx

API e Módulos

A biblioteca é modular. Você pode importar somente o que precisa.

1. `revealOnScroll` (Core)

A função principal para animar elementos quando eles entram na tela.

Importação:

import { revealOnScroll } from '@thecoderzeus/scroll-reveal-fx';

Uso Básico:

revealOnScroll({
  selector: '.my-element',
  effect: 'slide',
  direction: 'up'
});

Opções do Core:

Usando effect: 'custom'

Para controle total, você pode definir suas próprias animações em CSS. Ao usar effect: 'custom', a biblioteca apenas adiciona a classe definida em customClassName ao elemento quando ele se torna visível.

CSS:

/* Defina sua animação */
@keyframes fadeInRight {
  from {
    opacity: 0;
    transform: translateX(50px);
  }
  to {
    opacity: 1;
    transform: translateX(0);
  }
}

/* Oculte o elemento inicialmente */
.my-custom-animation {
  opacity: 0;
}

/* Aplique a animação quando a classe for adicionada */
.my-custom-animation.is-visible {
  animation: fadeInRight 1s forwards;
}

JavaScript:

revealOnScroll({
  selector: '.my-custom-animation',
  effect: 'custom',
  // customClassName: 'is-visible' // Opcional, usa o padrão
});

2. `animateText`

Para animar texto com múltiplos efeitos.

Importação:

import { animateText } from '@thecoderzeus/scroll-reveal-fx';

Uso:

1. Efeitos Padrão (Fade, Slide, etc.)

// Anima cada letra com um efeito de 'fade' e ordem aleatória
animateText({
  selector: '.my-title',
  splitType: 'chars', // 'chars' ou 'words'
  effect: 'fade',     // Qualquer efeito do core: slide, scale, etc.
  randomOrder: true,  // Opcional: revela em ordem aleatória
  stagger: 30
});

2. Efeito Máquina de Escrever (Typewriter)

// Simula o texto sendo digitado
animateText({
  selector: '.my-paragraph',
  effect: 'typewriter',
  typewriterSpeed: 40, // Velocidade em ms por caractere
  once: false,         // Opcional: repete a animação
  reset: true
});

Opções Adicionais:

(Herda todas as outras opções do revealOnScroll para os efeitos padrão)

3. `drawSVG`

Anima o traçado de caminhos (<path>) dentro de um SVG.

Importação:

import { drawSVG } from '@thecoderzeus/scroll-reveal-fx';

Uso:

<svg id="my-logo" ...>
  <path d="..."/>
  <path d="..."/>
</svg>

drawSVG({
  selector: '#my-logo',
  duration: 3000,
  stagger: 300,
  once: false,
  reset: true
});

(Herda opções de duração, stagger, delay, once, reset, etc.)

4. `applyParallax`

Aplica um efeito de parallax a um elemento durante o scroll.

Importação:

import { applyParallax } from '@thecoderzeus/scroll-reveal-fx';

Uso:

applyParallax({
  selector: '.parallax-bg',
  intensity: 0.3
});

Opções:

5. `scrubAnimation`

Vincula o progresso de uma animação diretamente à posição da barra de rolagem.

Importação:

import { scrubAnimation } from '@thecoderzeus/scroll-reveal-fx';

Uso:

scrubAnimation({
  trigger: '#track',
  target: '.my-element',
  from: { rotate: 0, scale: 0.5 },
  to: { rotate: 180, scale: 1 },
  startOffset: 100, // Começa 100px depois do topo do trigger
  endOffset: -100   // Termina 100px antes do fundo do trigger
});

Opções:

6. `createTimeline`

Orquestra múltiplas animações a partir de um único gatilho.

Importação:

import { createTimeline } from '@thecoderzeus/scroll-reveal-fx';

Uso:

const myTimeline = createTimeline({ trigger: '#start-sequence' });

myTimeline
  .add({ selector: '.title', effect: 'slide', direction: 'down' })
  .add({ selector: '.subtitle', effect: 'fade' })
  .add({ selector: '.card', effect: 'scale', stagger: 100, once: false });

Opções (createTimeline):

A função .add() aceita qualquer opção válida para revealOnScroll.

7. `createScrollSpy`

Cria um "espião de rolagem" que aplica uma classe ativa nos links de navegação conforme a seção correspondente entra no campo de visão.

Importação:

import { createScrollSpy } from '@thecoderzeus/scroll-reveal-fx';

Uso:

<nav>
  <a href="#section1" class="nav-link">Section 1</a>
  <a href="#section2" class="nav-link">Section 2</a>
</nav>
<main>
  <section id="section1" class="content-section">...</section>
  <section id="section2" class="content-section">...</section>
</main>

createScrollSpy({
  links: '.nav-link',
  sections: '.content-section',
  activeClassName: 'is-active' // opcional
});

Opções:

8. `applyTilt`

Aplica um efeito de inclinação 3D interativo baseado no mouse.

Importação:

import { applyTilt } from '@thecoderzeus/scroll-reveal-fx';

Uso:

applyTilt({
  selector: '.interactive-card',
  intensity: 15,
  scale: 1.05
});

(Herda opções de easing e reset)

9. `applyMagnetism`

Cria um efeito "magnético" onde um elemento é atraído pelo cursor do mouse quando ele se aproxima.

Importação:

import { applyMagnetism } from '@thecoderzeus/scroll-reveal-fx';

Uso:

applyMagnetism({
  selector: '.magnetic-button',
  intensity: 0.3,
  threshold: 80
});

Opções:

License

Este projeto está licenciado sob a Licença MIT.

Novos Módulos de Animação

applyWaveReveal

Revela elementos com um movimento vertical em forma de onda combinado com um fade de opacidade ao rolar a página.

Importação:

import { applyWaveReveal } from '@thecoderzeus/scroll-reveal-fx';

Uso:

applyWaveReveal({
  selector: '.wave-reveal',
  duration: 800,
  stagger: 100,
  easing: 'ease-out',
  once: true
});

Opções:

applyFlip3D

Revela elementos com uma animação de flip 3D ao rolar a página.

Importação:

import { applyFlip3D } from '@thecoderzeus/scroll-reveal-fx';

Uso:

applyFlip3D({
  selector: '.flip3d-reveal',
  duration: 700,
  easing: 'ease-in-out',
  once: true
});

Opções:

applyColorPulse

Revela elementos com uma animação suave de pulso de cor ao rolar a página.

Importação:

import { applyColorPulse } from '@thecoderzeus/scroll-reveal-fx';

Uso:

applyColorPulse({
  selector: '.color-pulse',
  pulseColor: '#ff4081',
  duration: 1000,
  once: true
});

Opções:

applyZoomBlur

Revela elementos com um efeito de zoom com desfoque que desaparece ao completar a animação.

Importação:

import { applyZoomBlur } from '@thecoderzeus/scroll-reveal-fx';

Uso:

applyZoomBlur({
  selector: '.zoom-blur',
  duration: 700,
  easing: 'ease-out',
  once: true
});

Opções:

applySkewReveal

Revela elementos com um leve skew e slide, voltando ao estado normal no fim.

Importação:

import { applySkewReveal } from '@thecoderzeus/scroll-reveal-fx';

Uso:

applySkewReveal({
  selector: '.skew-reveal',
  axis: 'y',     // 'x' ou 'y'
  angle: 10,     // graus
  distance: 20,  // px
  duration: 700,
  easing: 'ease-out',
  once: true
});

Opções:

applyMaskWipe

Revela elementos com um “wipe” direcional usando clip-path.

Importação:

import { applyMaskWipe } from '@thecoderzeus/scroll-reveal-fx';

Uso:

applyMaskWipe({
  selector: '.mask-wipe',
  direction: 'left', // 'right' | 'top' | 'bottom'
  duration: 800,
  easing: 'ease-in-out',
  once: true
});

Opções:

applyCascadeReveal

Revela os filhos de um contêiner em sequência com stagger.

Importação:

import { applyCascadeReveal } from '@thecoderzeus/scroll-reveal-fx';

Uso:

applyCascadeReveal({
  selector: '.cascade',
  childSelector: '.cascade-item',
  duration: 600,
  stagger: 120,
  easing: 'ease-out',
  once: true
});

Opções:

Contribuição

Quer pedir um ajuste, corrigir um bug ou propor um novo efeito? Fique à vontade para abrir um Pull Request.

Como contribuir

Faça um fork do repositório: GitHub - scroll-reveal-fx
Crie uma branch descritiva: feat/nome-do-efeito ou fix/descricao-breve
Implemente e teste seguindo a estrutura de pastas:
- src/core/*, src/effects/*, src/mouse/*
Siga o estilo do código (nomes claros, sem dependências externas)
Abra um PR descrevendo:
- O problema que resolve ou o novo efeito
- Um exemplo de uso (código) e breve explicação
- Antes/Depois se for correção

Se preferir, abra uma Issue descrevendo o que precisa ser ajustado.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@thecoderzeus/scroll-reveal-fx

Features

Installation

API e Módulos

1. revealOnScroll (Core)

2. animateText

3. drawSVG

4. applyParallax

5. scrubAnimation

6. createTimeline

7. createScrollSpy

8. applyTilt

9. applyMagnetism

License

Novos Módulos de Animação

applyWaveReveal

applyFlip3D

applyColorPulse

applyZoomBlur

applySkewReveal

applyMaskWipe

applyCascadeReveal

Contribuição

Como contribuir

1. `revealOnScroll` (Core)

2. `animateText`

3. `drawSVG`

4. `applyParallax`

5. `scrubAnimation`

6. `createTimeline`

7. `createScrollSpy`

8. `applyTilt`

9. `applyMagnetism`