Shadergradient

ShaderGradient Integration

Use this skill to add high-quality animated gradient backgrounds with @shadergradient/react.

When To Use

• User asks for ShaderGradient integration in React or Next.js
• User wants animated gradient hero/background sections
• User mentions @shadergradient/react or shadergradient.co settings URLs
• User needs tuneable color/animation gradients with Three.js

Install

Install required runtime packages:

npm i @shadergradient/react @react-three/fiber three three-stdlib camera-controls
npm i -D @types/three

Baseline Usage

Use ShaderGradient inside ShaderGradientCanvas.

import { ShaderGradient, ShaderGradientCanvas } from "@shadergradient/react";

export function GradientBackground() {
  return (
    <ShaderGradientCanvas style={{ position: "absolute", inset: 0 }} pixelDensity={1.5} fov={45}>
      <ShaderGradient cDistance={3.2} cPolarAngle={125} animate="on" />
    </ShaderGradientCanvas>
  );
}

Next.js Guidance

• Prefer a client component wrapper ("use client") for gradient components
• Mount as a visual background layer, then keep content in a positioned foreground container
• Keep pixelDensity conservative (for example 1 to 1.5) on heavy pages
• Avoid multiple full-screen gradient canvases on the same route

Preset From URL

If user gives a settings URL, load it directly:

<ShaderGradientCanvas>
  <ShaderGradient control="query" urlString="https://www.shadergradient.co/customize?...your-settings..." />
</ShaderGradientCanvas>

Performance Checklist

• Start with animate="off" when debugging layout, enable after placement is correct
• Reduce uStrength, uFrequency, and pixelDensity for lower-end devices
• Keep gradient isolated from expensive re-render trees
• Check for reduced motion preferences before enabling aggressive animation

Common Defaults

• type: plane
• lightType: 3d
• animate: on
• cDistance: 3 to 4
• cPolarAngle: 90 to 125
• pixelDensity: 1 to 1.5

Extra Reference

• For property details and patterns, see reference.md