@frederico-kluser/matrix-rain

v1.0.1

Published

15 days ago

Customizable Matrix-style digital rain effect for web applications. Works with vanilla JavaScript/TypeScript or React.

0High
0Medium
0Low

frederico-kluser

matrix rain digital-rain canvas animation effect react typescript cyberpunk background visual-effect

@frederico-kluser/matrix-rain

Uma biblioteca customizavel para criar o icônico efeito "Matrix Rain" (chuva digital) em aplicações web. Funciona com JavaScript/TypeScript puro ou React.

Caracteristicas

Zero Dependencias - A versão vanilla não requer nenhuma biblioteca externa
TypeScript First - Totalmente tipado com tipos exportados
React Ready - Componente React pronto para uso
Altamente Customizavel - Cores, velocidade, caracteres e muito mais
Performance Otimizada - Usa Canvas API para renderização eficiente
Responsivo - Adapta-se automaticamente ao redimensionamento
Sem Scroll - O efeito permanece fixo, não interferindo na rolagem da página

Instalação

# npm
npm install @frederico-kluser/matrix-rain

# yarn
yarn add @frederico-kluser/matrix-rain

# pnpm
pnpm add @frederico-kluser/matrix-rain

Uso Rápido

JavaScript/TypeScript Vanilla

import { MatrixRain } from '@frederico-kluser/matrix-rain';

// Selecione o container
const container = document.getElementById('matrix-container');

// Crie a instância
const rain = new MatrixRain(container);

// Inicie o efeito
rain.start();

// Para parar/destruir quando necessário
rain.destroy();

React

import { MatrixRainBackground } from '@frederico-kluser/matrix-rain';

function App() {
  return (
    <div>
      {/* Background fullscreen */}
      <MatrixRainBackground fullscreen />

      {/* Seu conteúdo aqui */}
      <main style={{ position: 'relative', zIndex: 1 }}>
        <h1>Meu Site</h1>
      </main>
    </div>
  );
}

Guia Completo

1. Background Fullscreen (Tela Inteira)

O uso mais comum - um background Matrix que cobre toda a tela sem interferir no scroll.

HTML/JavaScript

<!DOCTYPE html>
<html>
<head>
  <style>
    /* Container fixo para o efeito */
    #matrix-background {
      position: fixed;
      top: 0;
      left: 0;
      width: 100vw;
      height: 100vh;
      z-index: 0;
      pointer-events: none;
    }

    /* Seu conteúdo fica acima */
    .content {
      position: relative;
      z-index: 1;
    }
  </style>
</head>
<body>
  <div id="matrix-background"></div>

  <div class="content">
    <h1>Seu conteúdo aqui</h1>
    <!-- Scroll funciona normalmente -->
  </div>

  <script type="module">
    import { MatrixRain } from '@frederico-kluser/matrix-rain';

    const container = document.getElementById('matrix-background');
    const rain = new MatrixRain(container, {
      opacity: 0.5, // Transparência do canvas
    });
    rain.start();
  </script>
</body>
</html>

React

import { MatrixRainBackground } from '@frederico-kluser/matrix-rain';

function App() {
  return (
    <>
      {/* fullscreen + zIndex baixo = background perfeito */}
      <MatrixRainBackground fullscreen zIndex={0} opacity={0.5} />

      {/* Conteúdo com z-index maior */}
      <main style={{ position: 'relative', zIndex: 1 }}>
        <h1>Bem-vindo</h1>
        <p>O scroll funciona normalmente!</p>
      </main>
    </>
  );
}

2. Dentro de um Container Específico

Renderize o efeito dentro de uma div com dimensões definidas.

HTML/JavaScript

<div id="matrix-box" style="width: 400px; height: 300px;"></div>

<script type="module">
  import { MatrixRain } from '@frederico-kluser/matrix-rain';

  const container = document.getElementById('matrix-box');
  const rain = new MatrixRain(container, {
    opacity: 0.8,
    fontSize: 12,
  });
  rain.start();
</script>

React

function MatrixCard() {
  return (
    <div style={{ width: '400px', height: '300px', position: 'relative' }}>
      <MatrixRainBackground opacity={0.8} fontSize={12} />

      {/* Conteúdo dentro do card */}
      <div style={{ position: 'relative', zIndex: 1, padding: '1rem' }}>
        <h2>Card com Matrix</h2>
      </div>
    </div>
  );
}

3. Cores Personalizadas

Mude as cores para criar temas diferentes.

const rain = new MatrixRain(container, {
  colors: {
    head: '#FF00FF',       // Cor do caractere líder (cabeça)
    trailBright: '#CC00CC', // Trail brilhante
    trailMedium: '#990099', // Trail médio
    trailDark: '#660066',   // Trail escuro
    background: '#1a001a',  // Cor de fundo
  },
});

Temas Prontos

// Tema Clássico (Verde - padrão)
const classicTheme = {
  head: '#FFFFFF',
  trailBright: '#00FF41',
  trailMedium: '#008F11',
  trailDark: '#003B00',
  background: '#000000',
};

// Tema Cyberpunk (Roxo/Rosa)
const cyberpunkTheme = {
  head: '#FF00FF',
  trailBright: '#CC00CC',
  trailMedium: '#990099',
  trailDark: '#660066',
  background: '#0d001a',
};

// Tema Azul
const blueTheme = {
  head: '#FFFFFF',
  trailBright: '#00BFFF',
  trailMedium: '#0080AA',
  trailDark: '#004466',
  background: '#000011',
};

// Tema Vermelho (Alerta)
const redTheme = {
  head: '#FFFFFF',
  trailBright: '#FF4444',
  trailMedium: '#AA2222',
  trailDark: '#661111',
  background: '#110000',
};

// Tema Dourado
const goldTheme = {
  head: '#FFFFFF',
  trailBright: '#FFD700',
  trailMedium: '#CC9900',
  trailDark: '#806600',
  background: '#0d0d00',
};

4. Caracteres Personalizados

Troque os caracteres exibidos na chuva.

// Apenas números
const rain = new MatrixRain(container, {
  characters: '0123456789',
});

// Apenas símbolos
const rain = new MatrixRain(container, {
  characters: '@#$%^&*()!?<>{}[]',
});

// Katakana japonês (original do filme)
const rain = new MatrixRain(container, {
  characters: 'アイウエオカキクケコサシスセソタチツテトナニヌネノハヒフヘホマミムメモヤユヨラリルレロワヲン',
});

// Binário
const rain = new MatrixRain(container, {
  characters: '01',
});

// Hexadecimal
const rain = new MatrixRain(container, {
  characters: '0123456789ABCDEF',
});

5. Controles de Velocidade e Performance

const rain = new MatrixRain(container, {
  // Tamanho da fonte (afeta densidade)
  fontSize: 14,

  // Intervalo entre frames em ms (menor = mais rápido, mais CPU)
  frameInterval: 50, // ~20 FPS (padrão)

  // Duração do fade em ms (maior = trails mais longos)
  fadeDuration: 8000, // 8 segundos

  // Intervalo mínimo entre criação de caracteres (frames)
  minDropInterval: 1,

  // Intervalo máximo entre criação de caracteres (frames)
  maxDropInterval: 3,

  // Opacidade do trail (menor = trails mais longos)
  trailOpacity: 0.05,
});

6. Controlando a Animação

const rain = new MatrixRain(container);

// Inicia a animação
rain.start();

// Pausa a animação
rain.pause();
// ou
rain.stop();

// Resume a animação
rain.resume();
// ou
rain.start();

// Limpa o canvas (mantém instância)
rain.clear();

// Verifica se está rodando
if (rain.isActive()) {
  console.log('Animação está rodando');
}

// Atualiza configurações em tempo real
rain.setOptions({
  opacity: 0.8,
  fontSize: 16,
});

// Obtém configurações atuais
const config = rain.getOptions();
console.log(config);

// Destrói completamente (remove canvas do DOM)
rain.destroy();

API Reference

Classe `MatrixRain`

Constructor

new MatrixRain(container: HTMLElement, options?: MatrixRainOptions)

Métodos

| Método | Descrição | |--------|-----------| | start() | Inicia a animação | | stop() | Para a animação | | pause() | Alias para stop() | | resume() | Alias para start() | | clear() | Limpa o canvas | | destroy() | Remove o canvas e limpa recursos | | isActive() | Retorna true se animação está rodando | | setOptions(options) | Atualiza configurações | | getOptions() | Retorna configurações atuais |

Componente `MatrixRainBackground` (React)

<MatrixRainBackground
  // Layout
  fullscreen?: boolean    // Se true, usa position: fixed (default: false)
  zIndex?: number         // Z-index do container (default: 0)
  className?: string      // Classe CSS adicional
  style?: CSSProperties   // Estilos inline adicionais

  // Aparência
  opacity?: number        // Opacidade do canvas 0-1 (default: 0.5)
  fontSize?: number       // Tamanho da fonte em px (default: 14)
  characters?: string     // Caracteres a usar

  // Cores
  colors?: {
    head?: string         // Cor da cabeça (default: '#FFFFFF')
    trailBright?: string  // Trail brilhante (default: '#00FF41')
    trailMedium?: string  // Trail médio (default: '#008F11')
    trailDark?: string    // Trail escuro (default: '#003B00')
    background?: string   // Fundo (default: '#000000')
  }

  // Performance
  frameInterval?: number  // ms entre frames (default: 50)
  fadeDuration?: number   // ms de fade (default: 8000)
  trailOpacity?: number   // Opacidade do trail (default: 0.05)
  minDropInterval?: number // Min frames entre drops (default: 1)
  maxDropInterval?: number // Max frames entre drops (default: 3)
/>

Interface `MatrixRainOptions`

interface MatrixRainOptions {
  fontSize?: number;        // default: 14
  characters?: string;      // default: Katakana + Alphanumeric
  frameInterval?: number;   // default: 50
  fadeDuration?: number;    // default: 8000
  opacity?: number;         // default: 0.5
  colors?: MatrixColors;
  minDropInterval?: number; // default: 1
  maxDropInterval?: number; // default: 3
  trailOpacity?: number;    // default: 0.05
}

interface MatrixColors {
  head?: string;        // default: '#FFFFFF'
  trailBright?: string; // default: '#00FF41'
  trailMedium?: string; // default: '#008F11'
  trailDark?: string;   // default: '#003B00'
  background?: string;  // default: '#000000'
}

Dicas de Performance

Use opacity baixo - Valores menores (0.3-0.5) reduzem a carga visual e melhoram performance em dispositivos mais lentos.
Aumente frameInterval - O padrão é 50ms (~20 FPS). Para economizar CPU, use 100ms (~10 FPS).
Aumente fontSize - Fontes maiores = menos colunas = menos cálculos.
Use em containers menores - Fullscreen em monitores 4K pode ser pesado. Considere usar em áreas específicas.
Destrua quando não visível - Se o usuário navegar para outra página/aba, destrua a instância.

// Exemplo: destruir quando não visível
document.addEventListener('visibilitychange', () => {
  if (document.hidden) {
    rain.pause();
  } else {
    rain.resume();
  }
});

Compatibilidade com Navegadores

Chrome 60+
Firefox 55+
Safari 11+
Edge 79+

Requer suporte a:

Canvas 2D API
ES6 Classes
ResizeObserver

Estrutura do Projeto

matrix-rain/
├── src/
│   ├── core/
│   │   ├── MatrixRain.ts     # Classe principal
│   │   ├── types.ts          # Tipos TypeScript
│   │   ├── constants.ts      # Constantes (cores, caracteres)
│   │   ├── utils.ts          # Funções utilitárias
│   │   └── index.ts          # Exports do core
│   ├── react/
│   │   ├── MatrixRainBackground.tsx  # Componente React
│   │   └── index.ts          # Exports do React
│   └── index.ts              # Entry point principal
├── examples/
│   ├── vanilla.html          # Exemplo JavaScript puro
│   └── react-example.tsx     # Exemplo React
├── package.json
├── tsconfig.json
├── README.md
└── LICENSE

Desenvolvimento Local

# Clone o repositório
git clone https://github.com/frederico-kluser/vibe_god.git
cd vibe_god/matrix-rain

# Instale dependências
npm install

# Build
npm run build

# Watch mode
npm run dev

Contribuindo

Contribuições são bem-vindas! Por favor:

Faça fork do projeto
Crie uma branch para sua feature (git checkout -b feature/nova-feature)
Commit suas mudanças (git commit -m 'feat: adiciona nova feature')
Push para a branch (git push origin feature/nova-feature)
Abra um Pull Request

Licença

MIT License - veja o arquivo LICENSE para detalhes.

Créditos

Inspirado pelo icônico efeito visual do filme "The Matrix" (1999).

Feito com 💚 por Vibe God

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@frederico-kluser/matrix-rain

Caracteristicas

Instalação

Uso Rápido

JavaScript/TypeScript Vanilla

React

Guia Completo

1. Background Fullscreen (Tela Inteira)

HTML/JavaScript

React

2. Dentro de um Container Específico

HTML/JavaScript

React

3. Cores Personalizadas

Temas Prontos

4. Caracteres Personalizados

5. Controles de Velocidade e Performance

6. Controlando a Animação

API Reference

Classe MatrixRain

Constructor

Métodos

Componente MatrixRainBackground (React)

Interface MatrixRainOptions

Dicas de Performance

Compatibilidade com Navegadores

Estrutura do Projeto

Desenvolvimento Local

Contribuindo

Licença

Créditos

Classe `MatrixRain`

Componente `MatrixRainBackground` (React)

Interface `MatrixRainOptions`