Animated ASCII Backgrounds for Web Apps – ASCIIGround.js

ASCIIGround is a JavaScript library that creates animated or static ASCII backgrounds with multiple pattern options.

Features

• Multiple Animations: Perlin noise, sine waves, digital rain, static noise, Japanese Matrix rain, and more
• Customizable Character Sets: Define your own ASCII characters for different visual effects
• Responsive Design: Automatically adapts to canvas resizing and viewport changes
• Performance Optimized: Efficient rendering loop with configurable frame rates
• Full-Page Utility: Helper function for creating full-screen ASCII backgrounds
• Flexible Styling: Custom fonts, colors, and background colors
• Module Support: Works with both ES modules and UMD/CDN implementations

How to use it:

1. Install ASCIIGround with NPM:

# NPM
$ npm install asciiground

2. Or use the UMD build:

<script src="/dist/asciiground.umd.js"></script>

3. Create an HTML5 canvas element on your webpage:

<canvas id="example"></canvas>

4. Get the canvas element, create a pattern instance (PerlinNoise pattern in this example), and instantiate ASCIIGround:

• frequency – the base frequency of the Perlin noise. Higher values result in more rapid changes.
• octaves – the number of noise layers to combine for fractal noise. More octaves add detail.
• persistence – controls the amplitude of each octave. Lower values reduce the influence of higher octaves.
• lacunarity – controls the frequency of each octave. Higher values increase the frequency.
• seed – the seed value for random number generation used to ensure reproducible noise patterns.
• characters – array of characters to use for rendering, ordered from lowest to highest intensity

import { ASCIIGround, PerlinNoisePattern } from 'asciiground';
// Acquire canvas element.
const canvas = document.getElementById('example') as HTMLCanvasElement;
// Create pattern instance.
const pattern = new PerlinNoisePattern({ 
  frequency: number;
  octaves: number;
  persistence: number;
  lacunarity: number;
  seed: number;
  characters: array,
});
// Create and initialize renderer.
const asciiGround = new ASCIIGround()
.init(canvas, pattern, { 
  // rednerer options here 
})
.startAnimation();

// Browser
const canvas = document.getElementById('example');
const pattern = new PerlinNoisePattern({ 
  // options here
});
const asciiGround = new ASCIIGround()
.init(canvas, pattern, { 
  // options here
})
.startAnimation();

5. Create a digital rain background:

• rainDensity – density of rain drops (0-1). Higher values create more rain streams.
• minDropLength – minimum length of rain drops in characters.
• maxDropLength – maximum length of rain drops in characters.
• minSpeed – minimum falling speed multiplier for rain drops.
• maxSpeed – maximum falling speed multiplier for rain drops.
• mutationRate – probability of character mutation per frame (0-1).
• fadeOpacity – background fade opacity for trail effect (0-1).

import { ASCIIGround, RainPattern } from 'asciiground';
const pattern = new RainPattern({
  rainDensity: 0.8,
  minDropLength: 8,
  maxDropLength: 25,
  minSpeed: 0.5,
  maxSpeed: 1.5,
  mutationRate: 0.04,
  fadeOpacity: 0.2,
  headColor: '#FFFFFF',
  characters: ['█', '▓', '▒', '░', ' '],
});

6. Create a static noise background.

• seed: the seed value for random number generation used to ensure reproducible noise patterns.

import { ASCIIGround, StaticNoisePattern } from 'asciiground';
const pattern = new StaticNoisePattern({
  seend: 0,
  characters: ['█', '▓', '▒', '░', ' '],
});

7. Configuration options for the ASCII renderer.

/** Text color for rendered characters */
color: string;
/** Whether animation is enabled */
animated: boolean;
/** Animation speed multiplier */
animationSpeed: number;
/** Font size in pixels */
fontSize: number;
/** Font family to use for rendering */
fontFamily: string;
/** Background color */
backgroundColor: string;
/** Padding around the rendered area */
padding: number;
/** Renderer type to use */
rendererType: '2D' | 'WebGL';
/** Enable mouse interaction support */
enableMouseInteraction: boolean;
/** Horizontal spacing between characters. If not specified, auto-calculated based on character width */
charSpacingX?: number;
/** Vertical spacing between characters. If not specified, auto-calculated based on character height */
charSpacingY?: number;
/** Resize target for the renderer, defaults to window. */
resizeTo: Window | HTMLElement

Changelog:

v1.4.0 (02/22/2026)

• bugfixes

v1.1.2 (07/31/2025)

• make renderer respect resizeTo target padding

v1.1.1 (07/28/2025)

• add bundlesize configuration for UMD and ES modules
• bugfixes

v1.1.0 (07/27/2025)

• (api): update ASCIIGround class api methods
• add UI controls generator prototype
• allow setting characters to japanese rain pattern
• controls: add output type to control spec for a more streamlined value parsing
• pattern: add static noise pattern
• pattern: re-add japanese rain pattern
• perlin: change renderer architecture and add proper perlin noise implementation
• rain pattern: allow changing head (leading drop character) color in the rain pattern
• renderer: add resizeTo option to the renderer
• renderer: move animation speed to the renderer and update demo controls
• optimize canvas rendering: optimize rendering on controls change and fix incremental slowdown issue
• renderer: skip rendering if pattern output or renderer options did not change
• renderer: animation speed is not controlled by the renderer rather than an individual pattern
• perlin: new renderer API and pattern implementation
• refactor: location of the docs styles has changed
• refactor(api): renamed and updated animation control methods and renderer initialization
• lots of bugs fixed