bitrain-matrixx

v2.2.0

Published

5 months ago

A zero-dependency library that renders a Matrix-style bit-rain effect on the page background.

Downloads

0High
0Medium
0Low

hannyz

canvas matrix rain visual-effect web-component no-deps

🟩 Matrixx Canvas Web Component

A lightweight, zero-dependency Web Component package that renders an animated Matrix-style rain background using pure HTML, CSS, and JavaScript.

Includes:
<matrixx-canvas> – manages the canvas and columns
<bit-rain-column> – represents an individual animated column of binary bits shifting between 0&1.

📸 Screenshots

| Direction: Up | Direction: Down | |---------------|-----------------| | Density: Very High (10) | Density: Low (3) | | | Down | | Bits Color: blue | Bits Color: magenta | | | Down | | Rain Display: charamask (Cell Size=32) | Rain Display: charamask (Default) | | | Down |

Both screenshots captured using the <matrixx-canvas> component with different Custom Attributes.

📦 Installation

Install it via npm:

npm install bitrain-matrixx

🚀 Usage

1. Import the components

<script type="module">
  import 'bitrain-matrixx';
</script>

import 'bitrain-matrixx' auto-registers <matrixx-canvas>.

If you want manual registration:

import { defineMatrixx } from 'bitrain-matrixx/core';

defineMatrixx();

2. Use the `<matrixx-canvas>` tag

<matrixx-canvas
  density="0.7"
  direction="down"
  limit="true"
></matrixx-canvas>

3. Example with content on top

<body style="margin: 0; background: black;">
  <matrixx-canvas density="0.8" direction="up"></matrixx-canvas>

  <div style="position: relative; color: white; text-align: center; padding-top: 25vh;">
    <h1>Hello, Matrixx.</h1>
  </div>
</body>

4. Example with React

import 'bitrain-matrixx';
export default function App() {
  return (
      <div style={{ background: "black", width: '100vw', height: '100vh' }}>

        <matrixx-canvas
          rain-display="charamask"
          direction="down"
          density="6"
          cell-size="16"
          speed="20"
          tail-min="4"
          tail-max="12"
        ></matrixx-canvas>

        <div
          style={{
            position: "relative",
            color: "white",
            textAlign: "center",
            paddingTop: "25vh",
          }}
        >
          <h1>Hello, Matrixx.</h1>
        </div>
      </div>
  )
}

5. SSR frameworks (Next.js/Nuxt/SvelteKit)

For SSR stacks, import the package in a client-only boundary:

Next.js App Router: add 'use client' in the component that imports bitrain-matrixx
Nuxt: import inside if (import.meta.client) { await import('bitrain-matrixx') }
SvelteKit: import from a browser-only block or a client-only component

🧩 Custom Element Reference

`<matrixx-canvas>`

Attributes are all OPTIONAL, if you wish to have a kickstart, feel free to use a plain tag.

| Attribute | Type | Default | Description | | --------------- | ------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | density | float | 4.0 | Controls how many columns (or, in charamask, how many columns are likely to activate at once). Recommended: 1 ~ 10. | | direction | "up" | "down" | "up" | Direction of animation. For charamask, defines whether streaks travel from bottom → top (up) or top → bottom (down). | | bits-color | string | #00ff00 | Color used to render bits/characters. Defaults to lime-green. | | limit | bool | true | If true, restricts density within 0 ~ 10. If false, higher values allowed (may affect performance). | | rain-display | "riverflow" | "waterfall" | "charamask" | "riverflow" | Selects the effect mode: • riverflow – streams run continuously (0/1) • waterfall – drops fade before leaving screen (0/1) • charamask – lights up a fixed character grid with comet-like streaks | | cell-size | integer (px) | 18 | Charamask only. Pixel size of each grid cell (controls font size and spacing of bits). | | speed | float (cells/s) | 22 | Charamask only. Speed of streak heads, in grid cells per second. | | tail-min | integer (cells) | 6 | Charamask only. Minimum tail length for a streak (how many characters light up behind the head). | | tail-max | integer (cells) | 18 | Charamask only. Maximum tail length for a streak. Each streak chooses a random length between tail-min and tail-max. |

🛠 Technologies Used

Web Components: native HTMLElement extension via customElements.define
Shadow DOM: fully encapsulated styles
CSS animations: pure keyframe animations for performance
TypeScript: strict typing and dev-time safety
No dependencies: zero runtime overhead

📁 Project Structure

src/
├── bit-rain-column.ts   # <bit-rain-column> component
├── matrixx-canvas.ts    # <matrixx-canvas> component
├── charamask-engine.ts  # render engine for theme 'charamask'
├── index.ts             # core entry (manual define)
└── auto.ts              # auto-define entry

dist/
├── *.js                 # ESM output
├── *.cjs                # CJS output
└── *.d.ts               # type declarations

index.html               # test/demo page html
examples/                # demo examples on different frameworks
tsconfig.json
package.json
README.md                # this doc

🧪 Development & Testing

npm install
npm run build
npx http-server . -p 8080 -c-1
# Then open http://localhost:8080/index.html

Important: run the command above in the repo root (the folder that contains this README and index.html). If you only see foreground text but no rain lines, run npm run build again and hard-refresh the page (Ctrl+F5).

Run framework examples

This repo uses npm workspaces. Examples consume the local package via file:../.., so you do not need npm pack for local development.

Run examples from the repo root:

npm install
npm run build
npm run dev:nextjs
# or: dev:nuxtjs / dev:react-vite / dev:solidjs / dev:sveltekit / dev:vue

If you start http-server inside examples/, open:

http://localhost:8080/index.html (examples index page), or
one specific folder (nextjs/, nuxtjs/, react_vite/, solidjs/, sveltekit/, vue/) with its own framework dev command.

📄 License

🙌 Acknowledgements

Inspired by the iconic "Matrix" falling code effect. Built to be easy-to-use, flexible, and framework-free. Hope this would boost your ideas to web!