@unix/dapple-pattern

@unix/dapple-pattern is a browser-side Canvas 2D renderer for responsive procedural backgrounds. It provides preset-based visuals, live configuration, pointer effects, and a small lifecycle API without requiring a framework.

Install

pnpm add @unix/dapple-pattern

Usage

import { createDapplePattern, DAPPLE_PATTERN_PRESETS } from '@unix/dapple-pattern'

const canvas = document.querySelector<HTMLCanvasElement>('#background')

if (canvas) {
  const pattern = createDapplePattern(
    canvas,
    DAPPLE_PATTERN_PRESETS.HALFTONE_BLOOM_LIGHT,
  )

  pattern.update({ glow: 0.32, speed: 0.18 })
}

The canvas must have a non-zero CSS size. Rendering starts automatically; call destroy() when the canvas is removed.

API

createDapplePattern

createDapplePattern(
  canvas: HTMLCanvasElement,
  options?: DapplePatternOptions,
): DapplePatternController

Pass a preset or custom options as the second argument. Named presets are available from DAPPLE_PATTERN_PRESETS; theme-aware presets are available from DAPPLE_PATTERN_PRESET_VARIANTS.

Options

| Option | Description | | ---------------------- | ------------------------------------------------------------ | | pattern | Renderer key selected by a preset or custom configuration. | | mask | Reveal mode: none, spotlight, or vignette. | | angle | Line rotation in degrees. | | maxMarks | Maximum repeated marks drawn per frame. | | maxPixels | Maximum backing-store pixel count. | | backgroundColor | Canvas fill color; use transparent to preserve alpha. | | color | Base pattern color. | | accentColor | Secondary pattern or glow color. | | highlightColor | Tertiary color for multi-color patterns. | | ambientMotion | Enables time-based pattern movement. | | spacing | Distance between repeated marks in CSS pixels. | | size | Dot or line width in CSS pixels. | | variation | Renderer-specific shape, density, or displacement variation. | | opacity | Pattern opacity from 0 to 1. | | speed | Ambient movement multiplier. | | glow | Accent glow strength from 0 to 1. | | pointer | Enables pointer effects for compatible patterns. | | pointerIdleMode | Resting focus: none or center. | | pointerLeaveBehavior | Focus behavior after the pointer leaves. | | pointerRadius | Focus influence radius in CSS pixels. | | fps | Maximum animation frame rate. | | pixelRatio | Maximum device pixel ratio. | | respectReducedMotion | Freezes ambient motion when reduced motion is requested. |

Controller

• start() resumes rendering.
• stop() pauses rendering.
• resize() remeasures the canvas.
• update(options) merges options and redraws.
• options() returns the resolved options.
• snapshot() returns dimensions, runtime state, and resolved options.
• destroy() removes observers and event listeners.

Similar Projects

• unix/dapple: image-to-mark WebGL renderer.
• unix/dapple-flow: responsive animated glyph fields.

License

MIT