Docs

ASCII-blobs

Animated ASCII backgrounds for React and plain JavaScript. It maps gaussian blobs onto a grid using a pre-rendered glyph atlas. The draw cadence stays steady thanks to a capped delta and a reveal ramp.

What you get

  • React component with ref controls (pause, resume, reset, stats).
  • Vanilla class for framework-free use.
  • Typed configuration with safe defaults.
  • Built-in themes, plus customizable colors and glyph palette.
  • Styles inject automatically in both builds; standalone CSS is also available.

Defaults at a glance

  • 8 blobs using the character set " .,:;!~+=xoX#".
  • 14px cell size and a 42 ms frame interval (~24 fps draw budget).
  • 1200 ms reveal duration with a 400 ms fade.
  • Blur and offscreen canvas are on by default for smoother glyphs.

Install

ESM and CJS builds include TypeScript types, the vanilla bundle, and CSS. Styles inject automatically when you import the React or vanilla entry.

npm install ascii-blobs

For static use without a bundler, include ascii-blobs/dist/ascii-blobs.css and ascii-blobs/vanilla.mjs.

React usage

AsciiBlobs is a standard functional component. Styles inject once per page. Use the ref to pause, resume, reset, or check stats.

import { useRef } from "react";
import { AsciiBlobs, getThemeClassName } from "ascii-blobs";
import type { AsciiBlobsRef } from "ascii-blobs";

export function Hero() {
  const blobsRef = useRef<AsciiBlobsRef | null>(null);

  return (
    <section style={{ position: "relative", minHeight: "420px" }}>
      <AsciiBlobs
        ref={blobsRef}
        className={getThemeClassName("dracula")}
        style={{ position: "absolute", inset: 0, zIndex: -1 }}
        colors={{ primary: "#BD93F9" }}
        blobBehavior={{ count: 10 }}
        onReady={() => console.log("ASCII-blobs ready")}
      />
      <div style={{ position: "relative", padding: "48px 0" }}>
        <h2>Neon console vibes</h2>
        <button onClick={() => blobsRef.current?.reset()}>Refresh blobs</button>
      </div>
    </section>
  );
}
  • The CSS sets the wrapper to position: fixed and fills the viewport. Override this with style (as shown) to scope it to a container.
  • AsciiBlobsRef methods: pause(), resume(), reset(), and getStats().
  • onReady runs when the grid and glyph atlas are initialized. onBlobSpawn fires when a blob is created or recycled.

Vanilla usage (ESM)

The vanilla build is at ascii-blobs/vanilla. It renders into a wrapper inside your container and manages its own animation loop. It applies position: relative and overflow: hidden if not already set.

import { AsciiBlobs, getThemeClassName } from "ascii-blobs/vanilla";

const stage = document.querySelector("#stage");
const blobs = new AsciiBlobs(stage, {
  className: getThemeClassName("nord"),      // optional theme class
  style: { position: "absolute", inset: "0" },
  colors: { primary: "#88C0D0" },
  blobBehavior: { count: 6, maxRadius: 180 },
  animation: { frameInterval: 42 },          // draw budget in ms
});

// Controls
blobs.pause();
blobs.resume();
blobs.reset();
console.log(blobs.getStats()); // { blobCount, fps, isPaused }

// Cleanup
window.addEventListener("beforeunload", () => blobs.destroy());
Note: The wrapper defaults to position: fixed via CSS. To confine the effect, add a class or inline styles to change it to absolute.

Configuration reference

All fields are optional and fall back to defaults. Numeric values are clamped for safety (e.g., blob count ≥ 1, cell size ≥ 6, target FPS max 240).

Colors

FieldDefaultDescription
primaryrgb(100, 180, 255)Main glyph color.
background#000000Optional override for backdrop gradient stops.
glowrgba(100, 180, 255, 0.8)Glow tint in the glyph atlas.
shadowrgba(100, 180, 255, 0.4)Shadow tint in the glyph atlas.

Characters

characters (default " .,:;!~+=xoX#") maps characters to brightness levels. A small random bias per cell adds variation.

Blob behavior

FieldDefaultNotes
count8Number of active blobs to keep alive.
minSpeed/maxSpeed6 / 12Speed seeds. Remapped internally and scaled to the viewport.
minRadius/maxRadius60 / 140Size seeds. Remapped internally and scaled to the viewport.
spawnInterval3000 msControls lifespan variance and warm start offset.
lifespan30000 msTime before a blob is recycled.
fadeInDuration2000 msBlend-in time after spawning.
wobbleAmplitude0.15Scale variation for pulsation.
wobbleSpeed0.0004Angular speed for pulsation.
rotationSpeed0.00003Rotation speed (radians per ms).

Animation

FieldDefaultDetails
frameInterval42 msMinimum time between draws. If performance.targetFPS is set but this is undefined, it's calculated from the FPS target.
revealDuration1200 msDuration of the initial reveal ramp.
revealFade400 msFade-in time for each cell after its delay.

Performance

FieldDefaultDetails
cellSize14 pxGrid resolution. Lower values are sharper but more expensive.
gaussianLutSize1024Size of the gaussian falloff lookup table.
targetFPS60Used only if frameInterval is missing.
useOffscreenCanvastruePre-renders glyph atlas offscreen if supported.
enableBlurtrueApplies blur to the glyph atlas glow layer.

Other props

  • className: Appended to the wrapper (for themes).
  • style: Inline styles merged onto the wrapper (for positioning or z-index).
  • onReady: Called after canvases, grid, and glyph atlas are initialized.
  • onBlobSpawn: Called when a blob is created or recycled.
  • interactive: Present in types but currently unused.

API

React

<AsciiBlobs />

  • Props: AsciiBlobsConfig fields, className, and style.
  • CSS injects once on first import.
  • Unmounting cleans up animation frames and listeners.

Ref (AsciiBlobsRef)

  • pause() / resume()
  • reset(): Respawns blobs and restarts the reveal.
  • getStats(): Returns { blobCount, fps, isPaused }.
Vanilla

new AsciiBlobs(container, config?)

  • container: DOM element or selector string.
  • CSS injects automatically; wrapper appends to container.
  • destroy(): Tears down canvases, listeners, and DOM.
  • Methods match React ref: pause, resume, reset, getStats.
Advanced exports

Core helpers

  • mergeConfig, defaultConfig
  • createBlob, resetBlob, updateBlob, pickSpawnPoint
  • setupGrid, drawFrame, pickShadeIndex
  • gaussianFalloff, createGaussianSampler
  • Constants: CELL_SIZE, ASCII_PALETTE, GAUSSIAN_LUT_SIZE, etc.

Exposed for customization; the renderer uses these internally.

Themes and styling

Theme class names are exported via themes and getThemeClassName(ThemeName). Apply them via className (React) or the className config option (vanilla). Available themes:

default catppuccin-mocha catppuccin-latte dracula nord gruvbox tokyo-night

Set colors.background to quickly retint the base gradient. For deeper tweaks (accent layers, texture, vignette), add your own CSS targeting the wrapper class.

Performance tips

  • On slower devices, lower blobBehavior.count or raise animation.frameInterval.
  • cellSize has the biggest performance impact. Smaller cells show more detail but increase draw calls.
  • useOffscreenCanvas and enableBlur are on by default. Disable blur for crisper glyph edges.
  • The renderer debounces resize operations (180 ms) and caps delta time at 120 ms to avoid spikes.
  • For a warmed start, call reset() to refresh blob lifetimes without tearing down the instance.