Dotfield

Installable living stipple / pointillism particle library — thousands of named modes, deep customization, zero runtime dependencies.

• Live demo: trinlol.github.io/dotfield
• Docs: trinlol.github.io/dotfield/docs/
• npm: dotfield

Install (package dependency)

npm install dotfield

const Dotfield = require("dotfield");
// ESM-friendly CJS export also works with bundlers:
// import Dotfield from "dotfield";

const field = Dotfield.create(document.getElementById("dots"), {
  mode: "flow-calm-cw-mid",
  fillParent: true,
  palette: "terracotta",   // or [{r,g,b}, ...] / '#c45c3e'
  background: "cream",     // or {r,g,b} / '#f4efe6'
  speed: 1,
  intensity: 1.1,
  count: 2400,             // or density: 1.2
});

field.setMode("orbit-brisk-ccw-fine");
field.setConfig({ palette: "ocean", speedScale: 1.4, density: 1.2 });
field.listModes(); // 3000+ { id, label, family, … }
field.stop();
field.destroy();

Package entry: main + exports → lib/dotfield.js.

TypeScript declarations are included at index.d.ts. Live fields automatically pause simulation while the document is hidden or the canvas is offscreen, and adapt draw density when frame rate drops. Disable either behavior with autoPause: false or adaptiveQuality: false.

The published lib/dotfield.js artifact is assembled from ordered source fragments under src/runtime/. Run npm run build after changing runtime code; the package still ships as one browser/CommonJS-compatible file.

See examples/package-consumer/ in the repo for a minimal Node consumer sample.

Gallery & docs

• Live demo: https://trinlol.github.io/dotfield/
• Docs: https://trinlol.github.io/dotfield/docs/

Local preview (optional):

npm start   # static server; open the printed URL (default http://localhost:8080)

• Backdrop full-page field uses a rotating full-field mode (gallery never changes it)
• Large live preview updates on mode selection
• Search / filter modes; copy mode id + install snippet

Customization options

Option	Description
mode	Catalog mode id
palette / colors	Named palette, #hex, or [{r,g,b},…]
background / bg	Named bg, #hex, or {r,g,b}
speed / speedScale	Absolute speed or multiplier
intensity	Scales noise amplitude + pull
count / density	Particle count or relative density
scale, noiseAmp, spin, pull	Low-level motion knobs
fillParent, interactive, seed, autoStart	Field lifecycle
wrap	Loop particles across all four canvas edges when true
wrapInset	Off-screen gutter used before wrapping to the opposite side; slow edge-tangent particles are carried through the seam instead of forming border lanes (0 preserves exact-edge wrapping)
mouseMode	repel · attract · swirl · off
mouseForce / mouseRadius	Cursor strength & pixel radius (mode-tuned by default)
autoMouse	Re-tune radius/force on mode change (default true)
mouseSmooth	Pointer follow ease 0–1 (default 0.12)

Disable cursor entirely with interactive: false (or mouseMode: 'off' / mouseForce: 0).

Runtime: field.setConfig({ … }) merges overrides (kept across setMode).

Headless: Dotfield.createSimulation({ mode, seed, count, … }) then .step(dt).

Modes

3000+ parametric modes across 36 families (flow, orbit, constellation, wave, spiral, vortex, grid, ribbon, bloom, rain, figure-8, helix, scatter, pulse, drift, magnet, weave, halo, cascade, swarm, aurora, tide, lattice, comet, fog, mill, braid, echo, nexus, gyre, petal, cord, lance, stream, infinity, poles) × speed × spin × scale, plus tint variants.

Ids are stable strings, e.g. vortex-rush-ccw-vast, orbit-tint-ocean-tight.

API summary

API	Role
Dotfield.create(canvas, opts)	Live canvas field
Dotfield.createSimulation(opts)	Headless simulation
Dotfield.listModes() / getMode(id)	Catalog
field.setMode(id) / setConfig(opts)	Control
start / stop / destroy / pulse	Lifecycle

Tests

npm test              # catalog ≥1000, motion, customization
npm run test:gallery  # dual-field isolation + source wiring
npm run test:consumer # file: install + require('dotfield')
npm run test:browser  # Playwright gallery probe (optional)

License

MIT. Visual language inspired by modern AI brand films; not affiliated with Anthropic.