API reference

Everything you need, nothing you don’t.

Cheat sheet

Quick formulas that map to a visual mood.

Effect	Math logic	Visual feeling
Breathe	sin(t) * 0.5 + 0.5	Smooth pulsing (0 to 1)
Glitch	sin(t) + sin(t * 10) * 0.1	Electric vibration
Orbit	x: sin(t), y: cos(t)	Perfect circular motion
Chaos	sin(t + sin(t))	Organic drift

API reference

Minimal surface area, designed to stay predictable.

SineWaveGenerator Options

Option	Type	Default	Description
`el`	`string \| HTMLCanvasElement`	required	Canvas element or CSS selector
`waves`	`Wave[]`	`[]`	Array of wave configuration objects
`pixelRatio`	`number`	`devicePixelRatio`	Device pixel ratio override
`maxPixelRatio`	`number`	`2`	Maximum pixel ratio cap for memory/perf
`autoResize`	`boolean`	`true`	Automatically resize canvas on window resize

Wave Options

Option	Type	Default	Description
`amplitude`	`number`	`10`	Wave height in pixels
`wavelength`	`number`	`100`	Distance between wave peaks in pixels
`segmentLength`	`number`	`10`	Rendering segment length (lower = smoother)
`phase`	`number`	random	Initial phase offset (radians)
`speed`	`number`	random 0.5-1.0	Animation speed multiplier
`easing`	`function`	`Ease.sineInOut`	Easing function for wave shape
`rotate`	`number`	`0`	Rotation angle in degrees
`strokeStyle`	`string \| null`	`null`	Custom stroke color (CSS color or CanvasGradient)

Methods

Method	Returns	Description
`start()`	`this`	Start the animation loop (uses `requestAnimationFrame`)
`stop()`	`this`	Stop the animation loop and unbind events
`resize()`	`this`	Manually trigger canvas resize and gradient rebuild
`addWave(config)`	`this`	Add a wave dynamically at runtime
`removeWave(index)`	`this`	Remove wave by index
`setWaves(waves)`	`this`	Replace all waves in a single update
`setQualityPreset(preset)`	`this`	Apply a memory/performance preset: quality, balanced, battery
`destroy()`	`this`	Stop animation, unbind events, clear waves

Easing Functions

Function	Description
`Ease.sineInOut`	Smooth sine curve (default)
`Ease.sineIn`	Accelerating sine curve
`Ease.sineOut`	Decelerating sine curve
`Ease.linear`	Linear (no easing)

Browser support

Works everywhere the Canvas API is available.

Browser	Version	Status
Chrome / Edge	60+	Full support
Firefox	55+	Full support
Safari	11+	Full support
iOS Safari	11+	Full support
Samsung Internet	8+	Full support

Requires HTMLCanvasElement.getContext("2d") and requestAnimationFrame. No WebGL needed.

Framework guides

Use sine-wave-generator with any UI framework.

React

import { useEffect, useRef } from "react";

function Wave() {
  const ref = useRef(null);
  useEffect(() => {
    const gen = new SineWaveGenerator({
      el: ref.current,
      waves: [{ amplitude: 30, wavelength: 140 }],
    });
    gen.start();
    return () => gen.stop();
  }, []);
  return <canvas ref={ref} />;
}

Vue 3

<template>
  <canvas ref="canvas" />
</template>
<script setup>
import { ref, onMounted, onUnmounted } from "vue";
const canvas = ref(null);
let gen;
onMounted(() => {
  gen = new SineWaveGenerator({
    el: canvas.value,
    waves: [{ amplitude: 30, wavelength: 140 }],
  });
  gen.start();
});
onUnmounted(() => gen?.stop());
</script>

Angular

@Component({
  template: `<canvas #wave></canvas>`
})
export class WaveComponent implements AfterViewInit, OnDestroy {
  @ViewChild("wave") canvas!: ElementRef;
  private gen?: SineWaveGenerator;

  ngAfterViewInit() {
    this.gen = new SineWaveGenerator({
      el: this.canvas.nativeElement,
      waves: [{ amplitude: 30, wavelength: 140 }],
    });
    this.gen.start();
  }
  ngOnDestroy() { this.gen?.stop(); }
}

Performance

Tune defaults for smoothness, with knobs for heavy scenes.

requestAnimationFrame

All rendering uses requestAnimationFrame for battery-efficient 60fps. The loop auto-pauses when the tab is hidden.

IntersectionObserver

Demos on this page use IntersectionObserver to start animations only when visible, saving CPU and battery.

prefers-reduced-motion

When prefers-reduced-motion: reduce is active, animations slow down to respect motion preferences.

Cap pixel ratio

Use maxPixelRatio to avoid oversized buffers on high-DPI screens.

Increase segment length

Larger segments reduce per-frame points while preserving visual flow.

Reduce wave count

More waves increases draw cost; balance layering with frame budget.

Important: If you set a high maxPixelRatio, memory use grows quickly on large canvases.

Memory grows with (width × height × maxPixelRatio²). For quick tuning, try setQualityPreset("quality"), setQualityPreset("balanced"), or setQualityPreset("battery").

Troubleshooting

Common questions and solutions.

Why is my canvas blurry on Retina screens?

The library handles DPI scaling automatically. If you see blur, ensure you are not setting width/height attributes on the canvas manually. Let the library manage sizing via resize(). You can also lower maxPixelRatio to trade sharpness for performance.

Why isn't the wave moving?

Make sure you call generator.start() after setup. Also check that speed is a positive number. If prefers-reduced-motion is enabled in your OS, animations will slow down to respect the setting.

How do I resize the canvas when the window changes?

Set autoResize: true (the default). For containers that resize independently of the window, call generator.resize() manually inside a ResizeObserver callback.

Can I use this with server-side rendering (SSR)?

The library requires the DOM and Canvas API. Guard your import with a typeof window !== "undefined" check or use dynamic imports in Next.js/Nuxt.

Does this library support WebGL?

No. The library uses the 2D Canvas API exclusively. This keeps the bundle small and avoids GPU driver issues. For most wave visualizations, 2D Canvas provides sufficient performance.