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: fixedand fills the viewport. Override this withstyle(as shown) to scope it to a container. AsciiBlobsRefmethods:pause(),resume(),reset(), andgetStats().onReadyruns when the grid and glyph atlas are initialized.onBlobSpawnfires 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());
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
| Field | Default | Description |
|---|---|---|
primary | rgb(100, 180, 255) | Main glyph color. |
background | #000000 | Optional override for backdrop gradient stops. |
glow | rgba(100, 180, 255, 0.8) | Glow tint in the glyph atlas. |
shadow | rgba(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
| Field | Default | Notes |
|---|---|---|
count | 8 | Number of active blobs to keep alive. |
minSpeed/maxSpeed | 6 / 12 | Speed seeds. Remapped internally and scaled to the viewport. |
minRadius/maxRadius | 60 / 140 | Size seeds. Remapped internally and scaled to the viewport. |
spawnInterval | 3000 ms | Controls lifespan variance and warm start offset. |
lifespan | 30000 ms | Time before a blob is recycled. |
fadeInDuration | 2000 ms | Blend-in time after spawning. |
wobbleAmplitude | 0.15 | Scale variation for pulsation. |
wobbleSpeed | 0.0004 | Angular speed for pulsation. |
rotationSpeed | 0.00003 | Rotation speed (radians per ms). |
Animation
| Field | Default | Details |
|---|---|---|
frameInterval | 42 ms | Minimum time between draws. If performance.targetFPS is set but this is undefined, it's calculated from the FPS target. |
revealDuration | 1200 ms | Duration of the initial reveal ramp. |
revealFade | 400 ms | Fade-in time for each cell after its delay. |
Performance
| Field | Default | Details |
|---|---|---|
cellSize | 14 px | Grid resolution. Lower values are sharper but more expensive. |
gaussianLutSize | 1024 | Size of the gaussian falloff lookup table. |
targetFPS | 60 | Used only if frameInterval is missing. |
useOffscreenCanvas | true | Pre-renders glyph atlas offscreen if supported. |
enableBlur | true | Applies 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
<AsciiBlobs />
- Props:
AsciiBlobsConfigfields,className, andstyle. - 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 }.
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.
Core helpers
mergeConfig,defaultConfigcreateBlob,resetBlob,updateBlob,pickSpawnPointsetupGrid,drawFrame,pickShadeIndexgaussianFalloff,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.countor raiseanimation.frameInterval. cellSizehas the biggest performance impact. Smaller cells show more detail but increase draw calls.useOffscreenCanvasandenableBlurare 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.