gradient docs — Install, API, modes, presets, export

Install

npm install gradient-runtime

React projects also get <GradientMount>. Peer dep: react >= 17.

Quick start

Mount a single gradient

One element, one renderer.

<div id="hero" style="width:100%;height:100vh"></div>

<script src="gradient-runtime.global.js"></script>
<script>
  const preset = {
    presetVersion: 1,
    engineId: "grain-v1",
    params: {
      uniform_seed: 42,
      uniform_palette_colors_hex: [
        "#0a0a12", "#1a1a2e", "#2563eb", "#f97316"
      ],
      uniform_motion_speed: 0.6,
      uniform_flow_rotation_radians: 0.9,
      uniform_flow_drift_speed_x: 0,
      uniform_flow_drift_speed_y: 0,
      uniform_warp_strength: 0.5,
      uniform_warp_scale: 2.2,
      uniform_turbulence: 0.4,
      uniform_brightness: 1.05,
      uniform_contrast: 1.12,
      uniform_saturation: 1.2,
      uniform_grain_amount: 0.12,
      uniform_grain_size: 1.3,
      uniform_reduce_motion_enabled: 0,
    },
  };

  Gradient.mount("#hero", preset, { mode: "animated" });
</script>

Shared mount

One renderer, many elements. Use for repeated cards, buttons, or tiles.

Learn More

Contact

<button class="cta-btn">Sign Up</button>
<button class="cta-btn">Learn More</button>
<button class="cta-btn">Contact</button>

<script src="gradient-runtime.global.js"></script>
<script>
  const preset = "g2:WzY4LFs5ODU2MDgsNDM5...";

  const shared = Gradient.mountShared(".cta-btn", preset, {
    mode: "animated",
  });

  // After adding new elements to DOM:
  shared.rescan();
</script>

API

Gradient.mount(target, preset, options?)

Mount a dedicated renderer into one element.

Param	Type	Note
target	string \| HTMLElement	CSS selector or element
preset	GradientPreset \| string	Preset object or compact key
options.mode	"animated" \| "static" \| "hover"	Default: "animated"
options.resolutionScale	number	0.5–1. Default from preset
options.fpsCap	30 \| 60	Default from preset

Returns GradientInstance.

Gradient.mountShared(target, preset, options?)

Mount one shared renderer across multiple elements.

Param	Type	Note
target	string \| HTMLElement[] \| NodeList	Selector, elements, or NodeList
preset	GradientPreset \| string	Preset object or compact key
options.mode	"animated" \| "static"	Default: "animated". No hover
options.frameTransport	"auto" \| "2d" \| "bitmaprenderer"	Default: "auto"

Returns GradientSharedInstance.

<GradientMount> — React

Wrapper component. No refs or useEffect needed for single mounts.

Param	Type	Note
preset	GradientPreset \| string	Keep reference stable (constant or useMemo)
options	GradientMountOptions	Default mode: "hover"
className	string	Applied to wrapper div
children	ReactNode	Rendered above the gradient (z-index 1)

Instance methods

Shared by GradientInstance and GradientSharedInstance:

updatePreset(preset)Swap preset without remounting

updateOptions(opts)Change mode, resolution, etc.

pause()Pause animation loop

resume()Resume animation loop

resize()Force recalculate size

renderStill()Render single frame

destroy()Tear down, remove listeners

GradientSharedInstance also has:

rescan()Re-query DOM for new matching elements

Modes

animatedContinuous loop. Default for mount() and mountShared().

staticRenders one frame and stops.

hoverAnimates on hover/focus only. Single mount() only.

Gradient.mount("#bg", preset, { mode: "animated" });
Gradient.mount("#card", preset, { mode: "static" });
Gradient.mount("#btn", preset, { mode: "hover" });

Presets

Readable preset

Full JSON object. Copy from the generator.

const preset = {
  presetVersion: 1,
  engineId: "grain-v1",
  params: {
    uniform_seed: 42,
    uniform_palette_colors_hex: ["#0a0a12", "#1a1a2e", "#2563eb"],
    uniform_motion_speed: 0.6,
    uniform_flow_rotation_radians: 0.9,
    uniform_flow_drift_speed_x: 0,
    uniform_flow_drift_speed_y: 0,
    uniform_warp_strength: 0.5,
    uniform_warp_scale: 2.2,
    uniform_turbulence: 0.4,
    uniform_brightness: 1.05,
    uniform_contrast: 1.12,
    uniform_saturation: 1.2,
    uniform_grain_amount: 0.12,
    uniform_grain_size: 1.3,
    uniform_reduce_motion_enabled: 0,
  },
};

Compact key

Base64 string. Shorter, good for inline use.

// Compact key exported from the generator
const preset = "g2:WzY4LFs5ODU2MDgsNDM5NjAzOSwx...";

// Works anywhere a preset object works
Gradient.mount("#target", preset, { mode: "animated" });