background-clouds

background-clouds adds a lightweight, animated low-poly cloud bank behind a website. It uses a single canvas, has no runtime dependencies, pauses motion when the user prefers reduced motion, and exposes lifecycle methods for single-page apps.

Install

npm install background-clouds

Use

import { createCloudBackground } from "background-clouds";

const clouds = createCloudBackground({
  canvas: document.querySelector("#background-clouds"),
  seed: "my-site",
  speed: 0.8,
  opacity: 0.9
});

// Later, for example when unmounting a route:
clouds.destroy();

<canvas id="background-clouds" aria-hidden="true"></canvas>

#background-clouds {
  position: fixed;
  inset: 0;
  width: 100%;
  height: 100%;
  pointer-events: none;
  z-index: -1;
}

The canvas must be available before calling createCloudBackground. The returned controller has start(), stop(), resize(), setSeed(seed), and destroy() methods. seed may be a string or number; using the same seed produces the same cloud layout. speed and opacity default to 1 and accept non-negative numbers.

Options

Option	Default	Description
canvas	required	The <canvas> element to render into.
seed	random	A stable string or number for deterministic cloud placement.
speed	1	Drift multiplier. Set to 0 for still clouds.
opacity	1	Overall cloud opacity multiplier.
pixelRatio	2	Maximum device-pixel ratio used for rendering.
reducedMotion	media query	Set explicitly to override prefers-reduced-motion.

The package owns only the canvas pixels. Set the canvas’s stacking order, background color, and positioning in your site CSS.