Animated WebGL Gradients & Effects – instantshader

instantshader is a vanilla JavaScript library for animated WebGL gradient backgrounds.

It has 10+ shaders for fluid, glowing, fabric, and geometric patterns, plus 5 stackable effects for pixelation, dithering, halftone, ASCII, and tint on gradients or images.

The library accepts 2 to 8 hex colors, supports repeatable animation loops and exact-size frame export, and has a separate React component package.

Features

• OKLCh interpolation for multicolor gradient palettes.
• Bayer and blue-noise dithering patterns.
• Media sources including images, canvases, video frames, and ImageBitmap objects.
• Ordered effect layers with blending and opacity controls.
• Live palette, shader parameter, and playback controls.
• Responsive canvas sizing with device-pixel-ratio rendering capped at 2x.
• Seekable frame rendering for thumbnails and video encoders.

How To Use It

Installation

Install the core ESM package in a Vanilla JavaScript or TypeScript project:

npm install instantshader

For React apps, install the component package instead:

npm install @instantshader/react

Basic Usage

Give the container a width and height before mounting the shader.

<div id="gradient-hero" style="width: 100%; height: 360px;"></div>

import { mountGradient, halo } from "instantshader";
const hero = document.querySelector("#gradient-hero");
const gradient = mountGradient(hero, {
  shader: halo,
  colors: ["#170b39", "#7948d7", "#f476a4", "#ffd995"],
  params: { radius: 1.2, y: -0.7, glow: 0.7 },
});
// Keep gradient to update, pause, or dispose of the canvas later.

For a static HTML page, place the container shown above before this module script. Use this CDN example as an alternative to the npm import.

<script type="module">
  import { mountGradient, halo } from "https://cdn.jsdelivr.net/npm/instantshader/dist/index.js";
  mountGradient(document.querySelector("#gradient-hero"), {
    shader: halo,
    colors: ["#170b39", "#7948d7", "#f476a4", "#ffd995"],
  });
</script>

Choose a Shader

Change Colors and Animation Settings

Keep the returned handle to update a mounted gradient. setParams() merges new values into the current shader settings.

gradient.setColors(["#081d3d", "#178caa", "#74e6d0"]);
gradient.setParams({ radius: 0.45, y: 0, flares: 0.3 });
gradient.setSpeed(0.6);
gradient.pause();
gradient.resume();

Use seed to reproduce a composition and loopSeconds for an exactly repeating animation.

Loop duration is measured in animation seconds: a 30-second loop at speed: 2 takes 15 real seconds. Very short loops can alter the motion of individual shaders.

<div id="looping-gradient" style="width: 100%; height: 320px;"></div>

import { mountGradient, flow } from "instantshader";
const loopingGradient = mountGradient(document.querySelector("#looping-gradient"), {
  shader: flow,
  colors: ["#0d1439", "#7363ec", "#ed75c1"],
  seed: 7,
  loopSeconds: 30,
  speed: 1,
});

Apply Effects to a Gradient

mountStack() accepts a shader or media source followed by an ordered array of effects. The first effect is closest to the original image.

<div id="effect-gradient" style="width: 100%; height: 360px;"></div>

import { mountStack, bloom, dither, tint } from "instantshader";
const stack = mountStack(document.querySelector("#effect-gradient"), {
  source: { kind: "generator", shader: bloom, params: { petals: 10 } },
  colors: ["#171335", "#9e3884", "#f49268", "#f9e3a1"],
  effects: [
    {
      effect: dither,
      params: {
        pattern: "blueNoise",
        size: 4,
        colorMode: "palette",
        levels: 4,
        blend: "normal",
        opacity: 1,
      },
    },
    { effect: tint, params: { mode: "palette", amount: 0.35 } },
  ],
  loopSeconds: 30,
});

Apply Halftone or ASCII to an Image

Provide a local image at /images/sample-photo.jpg, or change the URL to an image on your site.

Media sources also accept HTMLCanvasElement, HTMLVideoElement, and ImageBitmap. Use fit: "contain" to display the entire image and background for any surrounding area.

<div id="image-effect" style="width: 100%; height: 420px;"></div>

import { mountStack, halftone } from "instantshader";
const image = new Image();
image.src = "/images/sample-photo.jpg";
await image.decode();
const imageEffect = mountStack(document.querySelector("#image-effect"), {
  source: { kind: "media", media: image, fit: "contain" },
  colors: ["#111827", "#faf4e7"],
  background: "#faf4e7",
  effects: [
    {
      effect: halftone,
      params: {
        ground: "paper",
        blend: "normal",
        shape: "dot",
        size: 18,
        colorMode: "duotone",
        ink: "#111827",
        paper: "#faf4e7",
      },
    },
  ],
});

For video, create a stack with the video element as media and call refreshMedia() when the frame advances.

Render a PNG Frame

renderGradientFrame() creates a detached canvas at an exact pixel size.

import { renderGradientFrame, strata } from "instantshader";
const { canvas, dispose } = renderGradientFrame({
  shader: strata,
  colors: ["#171335", "#a33a83", "#f2ad63", "#f9e6a9"],
  width: 1920,
  height: 1080,
  seed: 4,
  timeMs: 1500,
});
const pngDataUrl = canvas.toDataURL("image/png");
dispose();

For effect layers, renderStackFrame() also accepts source and effects. For video output, reuse a canvas with createRenderer() or createStackRenderer() and render every frame with renderAt(timeMs). An external video encoder is required to produce an MP4 file.

Use It in React & Next.js

import { Halo, dither } from "@instantshader/react";
export default function GradientHero() {
  return (
    <div style={{ height: 360, position: "relative" }}>
      <Halo
        colors={["#170b39", "#7948d7", "#f476a4", "#ffd995"]}
        params={{ radius: 1, y: -0.65 }}
        effects={[{ effect: dither, params: { size: 3, opacity: 0.5 } }]}
        style={{ width: "100%", height: "100%" }}
      />
    </div>
  );
}

Configuration and API Reference

`mountGradient(container, options)`

`mountStack(container, options)`

container is a real DOM element. options supplies a source and optional layers. A stack has the common animation options colors, seed, speed, and loopSeconds. Media sources accept HTML images, canvases, video elements, or ImageBitmap. The fit field is "cover" (default) or "contain". Generator parameters are numeric; effect parameters can be numbers, strings, or booleans. Each effect layer is enabled by default.

Mount Handle Methods

// Shared by MountHandle and StackHandle:
handle.setColors(colors);         // Replace the palette.
handle.setSpeed(1.5);             // Change playback speed.
handle.setLoopSeconds(20);        // Set the exact loop period.
handle.setLoopSeconds(undefined); // Disable looping (0 also disables it).
handle.pause();                   // Stop the animation frame loop.
handle.resume();                  // Resume playback.
handle.seek(2500);               // Jump to 2.5 seconds.
handle.getTimeMs();               // Read the playback position.
handle.canvas;                    // Read the HTML canvas element.
handle.dispose();                 // Stop rendering and release WebGL resources.
// Only on the MountHandle returned by mountGradient():
handle.setParams({ scale: 1.4 }); // Merge shader parameters.
// Only on the StackHandle returned by mountStack():
stack.setSource(source);          // Replace the generator or media source.
stack.setSourceParams({ petals: 8 }); // Merge generator parameters; no-op for media.
stack.setEffects(layers);         // Replace the ordered effect layers.
stack.setEffectParams(0, { size: 6 }); // Merge parameters into layer 0.
stack.refreshMedia();             // Upload the current media frame.
stack.getGridInfo();              // Read the grid data for enabled grid effects.

One-Shot and Seekable Rendering

Shader and Effect Discovery

Low-Level Utilities

React Component Props

Shader Parameters

flow

beam

bloom

halo

strata

dune

whorl

silk

nacre

burst

glint

Effect Parameters

Effect layers accept parameter overrides through params; unspecified fields use their defaults. For pixelate, dither, halftone, and ascii, sizes are measured in reference pixels at 1920 x 1080 and scale with output resolution.

The blend values are normal, multiply, screen, overlay, softLight, and colorDodge. blend and opacity are available for pixelate, dither, halftone, and ascii. tint uses its own amount setting.

Pixelate

Dither

Floyd-Steinberg and other error-diffusion algorithms are not included. For a full-frame dither, set blend: "normal" and opacity: 1.

Halftone

ASCII

Tint

Alternatives and Related Resources

• Create Fluid Gradient Animations With JavaScript – NeatGradients.js
• Create Animated Gradient Background With JavaScript – gradientify.js
• Recreate Balatro’s Animated Shader Effect with WebGL – balatroShader.js
• Animated ASCII Backgrounds for Web Apps – ASCIIGround.js
• Convert Images to Pixel Art with JS Dithering & Custom Palettes – Image-to-Pixel