Quick start
Call asciiBackground() with a target element and an optional options object. The canvas is automatically sized, attached, and updated on window resize.
import { asciiBackground } from 'asciify-engine';
// Minimal — defaults to wave background, auto color scheme
const { destroy } = asciiBackground('#hero');
// Full options
const { destroy } = asciiBackground(containerEl, {
type: 'aurora', // background type
opacity: 0.15, // canvas opacity
colorScheme: 'auto', // 'dark' | 'light' | 'auto'
fontSize: 14, // character density
speed: 1, // animation speed multiplier
interactive: true, // respond to mouse
});
// Always clean up:
destroy();How it works
- 01
Append canvas
A <canvas> element is appended to the target and absolutely positioned to fill the container. The target receives position: relative if it was static.
- 02
Render loop
A requestAnimationFrame loop calls the background's render function each frame, passing the current time, canvas size, and color palette.
- 03
Mouse interaction
Pointer events are captured on the canvas. Each renderer receives a normalized cursor position and applies type-specific interaction effects.
- 04
Color scheme
When colorScheme is "auto", a MediaQueryList watches prefers-color-scheme and re-derives the palette at runtime with no page reload.
- 05
Destroy
Calling destroy() cancels the RAF loop, removes all event listeners, and detaches the canvas from the DOM.
All types
Wave
Smooth oscillating waves flow horizontally across the canvas.
Rain
Matrix-style falling character streams drop from the top.
Stars
Sparse starfield — characters twinkle and drift slowly.
Pulse
Concentric ASCII rings expand outward from the center.
Noise
Perlin-noise field continuously shifts the character grid.
Grid
Perspective grid converges toward a vanishing-point horizon.
Aurora
Banded aurora-borealis color waves drift vertically.
Silk
Flowing silk-like interference patterns with smooth motion.
Void
Dark void with slowly expanding ASCII character clusters.
Morph
Characters continuously morph between shapes with fluid motion.
Fire
Upward-rising fire simulation with heat-gradient color.
DNA
Rotating double-helix strand rendered with ASCII characters.
Terrain
Scrolling landscape terrain using shaded density characters.
Circuit
Animated PCB circuit-board traces and junction nodes.
Low-level API
Each background type also exports a standalone render function for use in custom RAF loops or canvas compositing pipelines.
type BackgroundRenderFn = (
ctx: CanvasRenderingContext2D,
width: number,
height: number,
time: number, // elapsed seconds
colors: {
primary: string;
secondary: string;
background: string;
},
opacity: number, // 0–1
) => void;
import { renderAuroraBackground } from 'asciify-engine';
function myLoop(canvas: HTMLCanvasElement) {
const ctx = canvas.getContext('2d')!;
const colors = { primary: '#d4ff00', secondary: '#fff', background: '#0a0a0a' };
const start = performance.now();
const tick = () => {
const t = (performance.now() - start) / 1000;
ctx.clearRect(0, 0, canvas.width, canvas.height);
renderAuroraBackground(ctx, canvas.width, canvas.height, t, colors, 0.9);
requestAnimationFrame(tick);
};
requestAnimationFrame(tick);
}