@abhijeetsaraf/gradient-background

Zero-dependency animated WebGL mesh-gradient background. One framework-agnostic core that works in a plain <script> tag and as a React component. Colors are controlled by props/options, with an automatic fallback to CSS variables so you can theme via CSS (including light-dark() and a .dark / .light class).

• No runtime dependencies. React is an optional peer dependency.
• Two animated color "blobs" over a transparent canvas — drops on top of any background.
• Pauses rendering when scrolled off-screen; handles resize and device pixel ratio.
• Ships ESM + CJS (for bundlers) and a global IIFE build (for CDN / <script>).

Color format

Colors are [highlight, shadow]. Each color accepts:

• Hex: "#08872b", "#08872b80", "#abc"
• rgb() / rgba(): "rgba(8,135,43,0.8)"
• Comma floats (the CSS-variable format, 0–1): "0.03, 0.53, 0.17, 0.8"
• Array: [8, 135, 43, 0.8] (0–255) or [0.03, 0.53, 0.17, 0.8] (0–1)

If you omit colors, the effect reads these CSS variables (names configurable):

:root {
  --gradient-mesh-highlight: 0.475, 0.804, 0.576, 0.92;
  --gradient-mesh-shadow: 0.031, 0.529, 0.169, 0.8;
  --theme-transition-duration: 500ms; /* used when colors change */
}

Use in a plain HTML / static GitHub Pages site (no build step)

<section id="hero" style="position: relative; height: 100vh;">
  <h1>Hello</h1>
</section>

<script src="https://unpkg.com/@abhijeetsaraf/gradient-background/dist/gradient-background.global.js"></script>
<script>
  const bg = new GradientBackground("#hero", {
    colors: ["#08872b", "#7bcd93"],
  });
  // bg.setColors(["#1e40af", "#93c5fd"]);  // animated
  // bg.destroy();
</script>

Passing a container element (or selector) creates a fill-parent <canvas> inside it. Passing a <canvas> element uses it directly.

Use in React (Vite / CRA / Next)

npm install @abhijeetsaraf/gradient-background

import GradientBackground from "@abhijeetsaraf/gradient-background/react";

export default function Hero() {
  return (
    <section style={{ position: "relative", height: "100vh" }}>
      <GradientBackground colors={["#08872b", "#7bcd93"]} />
      <h1 style={{ position: "relative" }}>Hello</h1>
    </section>
  );
}

Omit colors to drive it entirely from CSS variables (e.g. for dark/light themes); changing the CSS var and re-rendering will animate to the new colors.

Use the core directly (bundlers, non-React)

import GradientBackground from "@abhijeetsaraf/gradient-background";

const bg = new GradientBackground("#hero", { colors: ["#08872b", "#7bcd93"] });

API

new GradientBackground(target, options?)

• target — a <canvas>, a container element, or a CSS selector string.
• options.colors — [highlight, shadow]. Omit to read CSS variables.
• options.cssVars — override variable names { highlight, shadow, transitionDuration }.
• options.element — element to read CSS variables from (default <html>).
• options.tuning — { blobRadius, blobEdge, distortion } (baked into the shader at construction).
• options.blendMode — CSS mix-blend-mode applied to the canvas.
• options.pauseWhenHidden — pause rendering off-screen (default true).

Methods: setColors(colors, { duration }), refreshFromCssVars({ duration }), setBlendMode(mode), destroy().

React <GradientBackground />

Props: colors, tuning, cssVars, blendMode, pauseWhenHidden, transitionDuration, plus className / style forwarded to the canvas.

Tuning knobs

• blobRadius (default 0.36) — blob size in UV units.
• blobEdge (default 0.85) — 0–1 edge softness.
• distortion (default 0.5) — how far the field smears each blob.

Development

npm install
npm run build   # outputs dist/ (esm, cjs, iife)

License

MIT