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.
| Direction: Up | Direction: Down |
|---|---|
| Density: Very High (10) | Density: Low (3) |
 |
 |
| Bits Color: blue | Bits Color: magenta |
 |
 |
| Rain Display: charamask (Cell Size=32) | Rain Display: charamask (Default) |
 |
 |
Both screenshots captured using the
<matrixx-canvas>component with different Custom Attributes.
Install it via npm:
npm install bitrain-matrixx<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();<matrixx-canvas
density="0.7"
direction="down"
limit="true"
></matrixx-canvas><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>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>
)
}For SSR stacks, import the package in a client-only boundary:
- Next.js App Router: add
'use client'in the component that importsbitrain-matrixx - Nuxt: import inside
if (import.meta.client) { await import('bitrain-matrixx') } - SvelteKit: import from a browser-only block or a client-only component
| 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. |
- Web Components: native
HTMLElementextension viacustomElements.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
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
npm install
npm run build
npx http-server . -p 8080 -c-1
# Then open http://localhost:8080/index.htmlImportant: 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, runnpm run buildagain and hard-refresh the page (Ctrl+F5).
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:vueIf 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.
Apache-2.0 License © 2025 Hanny Zhang
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!