word-wave

A high-performance canvas animation engine that renders floating text particles in a simplex-noise-driven wave pattern.

Live demo | npm

Features

• WebGL 2 instanced rendering — all particles drawn in a single GPU draw call, with automatic Canvas 2D fallback
• GPU displacement effects — composable effects (noise, wave, pulse, custom GLSL) computed in the vertex shader
• Pre-built glyph atlas for characters and whole words (no per-frame fillText)
• Simplex noise sampled on a coarse grid and bilinearly interpolated per particle
• Directional "beach wave" effect layered on top of the noise field
• Automatic IntersectionObserver pause when off-screen
• ResizeObserver for responsive canvas sizing
• prefers-reduced-motion support (renders a static pattern)
• CSS custom property theming (--word-wave-color, --word-wave-opacity)
• Framework-agnostic — works with vanilla JS, Angular, React, Vue, etc.

Install

npm install word-wave

Usage

import { WordWaveEngine } from 'word-wave';

const canvas = document.getElementById('wave') as HTMLCanvasElement;
const engine = new WordWaveEngine(canvas, {
  words: ['dark_mode', 'feature_flag', 'rollout'],
  speed: 0.015,
});

// Later:
engine.stop(); // pause
engine.start(); // resume
engine.destroy(); // full cleanup

The canvas must be inside a positioned parent element — the engine sizes itself to fill canvas.parentElement.

Options

All fields are optional. Unspecified fields use sensible defaults.

| Option | Type | Default | Description | | ---------------------- | ----------------------- | ----------------------- | -------------------------------------------------- | | words | string[] | Feature-flag names | Words displayed as floating text particles | | frequency | number | 0.008 | Noise field spatial frequency (lower = smoother) | | amplitude | number | 10 | Maximum noise-driven displacement (CSS px) | | speed | number | 0.01 | How fast the noise field evolves over time | | spacingX | number | 90 | Horizontal spacing between word centers (CSS px) | | spacingY | number | 20 | Vertical spacing between rows (CSS px) | | direction | number | 225 | Wave propagation direction in degrees | | propagation | number | 0.03 | Wave density (higher = more crests) | | waveAmplitude | number | 15 | Directional wave push distance (CSS px) | | font | string | '14px system-ui, ...' | CSS font shorthand | | respectReducedMotion | boolean | true | Static pattern if prefers-reduced-motion: reduce | | pauseOffScreen | boolean | true | Pause animation when canvas is not visible | | mode | 'character' \| 'word' | 'character' | Per-character or per-word displacement |

Effects

Effects move displacement computation to the GPU vertex shader, enabling more complex visual patterns without CPU overhead. They compose additively: each effect contributes a displacement that is summed together. When effects is provided, the legacy displacement parameters (frequency, amplitude, direction, propagation, waveAmplitude) are ignored. The top-level speed option is not ignored — it acts as a global time scale that multiplies the animation rate of all effects uniformly.

Basic usage

Omitting effects preserves the existing CPU-based behavior. To use GPU effects, pass an array of effect descriptors:

const engine = new WordWaveEngine(canvas, {
  words: ['hello', 'world'],
  effects: [
    { type: 'noise', frequency: 0.008, amplitude: 10 },
    { type: 'wave', direction: 225, propagation: 0.03, amplitude: 15 },
  ],
});

The speed option scales the time increment for every effect on every frame. Doubling it makes all effects animate twice as fast:

const engine = new WordWaveEngine(canvas, {
  words: ['hello', 'world'],
  speed: 0.02, // global time scale — affects all effects uniformly
  effects: [
    { type: 'noise', frequency: 0.008, amplitude: 10 },
    { type: 'wave', direction: 225, propagation: 0.03, amplitude: 15 },
  ],
});

Built-in effects

noise

3D simplex noise displacement.

| Parameter | Type | Default | Description | | ----------- | -------- | ------- | ----------------------------------------------------------- | | frequency | number | 0.008 | Spatial frequency — lower values produce larger-scale noise | | amplitude | number | 10 | Maximum displacement in CSS pixels | | speed | number | 0.01 | Time evolution rate | | yScale | number | 0.6 | Y-axis amplitude multiplier (relative to X) |

wave

Directional propagating wave.

| Parameter | Type | Default | Description | | ------------- | -------- | ------- | ------------------------------------------------ | | direction | number | 225 | Wave direction in degrees (0 = right, 90 = down) | | propagation | number | 0.03 | Wave density — higher values produce more crests | | amplitude | number | 15 | Push distance in CSS pixels | | speed | number | 2.0 | Time multiplier for wave propagation speed |

pulse

Radial ripple expanding from a point.

| Parameter | Type | Default | Description | | ----------- | -------- | ------- | ---------------------------------------------- | | centerX | number | 0.5 | Horizontal center (0–1 normalized to viewport) | | centerY | number | 0.5 | Vertical center (0–1 normalized to viewport) | | frequency | number | 0.05 | Ring spacing | | amplitude | number | 10 | Maximum displacement in CSS pixels | | speed | number | 1.0 | Time multiplier |

Composing effects

Effects stack additively. Order doesn't affect the visual result. Combine multiple effects for richer motion:

const engine = new WordWaveEngine(canvas, {
  words: ['composable', 'effects'],
  effects: [
    { type: 'noise', frequency: 0.005, amplitude: 8 },
    { type: 'wave', direction: 45, propagation: 0.02, amplitude: 12 },
    { type: 'wave', direction: 135, propagation: 0.025, amplitude: 10 },
  ],
});

Custom GLSL

The glsl effect type allows arbitrary vertex shader displacement code. The code is injected into the vertex shader without validation — GLSL runs in the browser's GPU sandbox, so there is no security boundary to enforce. You are responsible for writing correct shader code.

Your snippet receives:

• pos (vec2) — particle base position in CSS pixels
• time (float) — elapsed time
• u_resolution (vec2) — viewport size in CSS pixels
• d (vec2) — must be assigned; this is the displacement contribution from this effect
• params — each key becomes a float uniform accessible by name

Example: horizontal sine wave with vertical bias

const engine = new WordWaveEngine(canvas, {
  words: ['custom', 'displacement'],
  effects: [
    {
      type: 'glsl',
      params: { u_freq: 0.05, u_amp: 12.0, u_vbias: 0.003 },
      code: `
        float wave = sin(pos.x * u_freq + time) * u_amp;
        d = vec2(wave, pos.y * u_vbias);
      `,
    },
  ],
});

Canvas fallback

Effects require WebGL 2. When using the Canvas 2D fallback renderer, a static grid is displayed instead of animated displacement.

Migration

The effects option is fully optional. Omitting it preserves the existing CPU-based displacement behavior using the legacy parameters (frequency, amplitude, direction, etc.).

Color & Opacity

Color and opacity are controlled via CSS custom properties on the canvas element, not JS options. This lets you use standard CSS for theming (media queries, class toggles, CSS variables).

| Property | Default | Description | | --------------------- | ----------------- | -------------------------------- | | --word-wave-color | inherited color | Text color (any CSS color value) | | --word-wave-opacity | 0.15 | Base particle opacity (0–1) |

The engine reads these once at construction. To update, set the properties and recreate the engine.

Example: light/dark theming

canvas {
  --word-wave-color: #1e1e1e;
  --word-wave-opacity: 0.24;
}

@media (prefers-color-scheme: dark) {
  canvas {
    --word-wave-color: #a5a5a5;
    --word-wave-opacity: 0.12;
  }
}

// Recreate on scheme change to pick up new CSS values
const mq = window.matchMedia('(prefers-color-scheme: dark)');
mq.addEventListener('change', () => {
  engine.destroy();
  engine = new WordWaveEngine(canvas, opts);
});

If no CSS custom properties are set, the engine falls back to the canvas element's inherited CSS color for text color, and 0.15 for opacity.

Built with AI

This project was vibe-engineered with Claude (Anthropic) under human review and direction throughout.

License

MIT