Shaders (shaders.com) for React / Next.js

Build GPU-accelerated visual effects with the shaders npm package using the same component-tree mental model as JSX. No GLSL, no render loop, no manual GPU plumbing — stack <Shader> children, pass props, and treat the canvas like any other CSS-sized block.

This skill teaches the mental model, composition patterns, gotchas, and aesthetic discipline for the library. It does not mirror the component reference — for the full prop list of each component, defer to shaders.com/docs/components.

Out of scope: custom GLSL/WebGPU code, Three.js / react-three-fiber scenes, and DOM post-processing (use CSS filter / backdrop-filter first). Shaders needs a real GPU and a real <canvas> — it cannot run in pure SSR, Node, or Workers.

Mental model

1. One <Shader> = one <canvas> element. No matter how many children you nest, the output is always a single DOM canvas you size with normal CSS.
2. Children are visual layers, evaluated top-to-bottom, blended on the GPU. Same intuition as stacking divs with z-index.
3. Two component families:
   • Generators create pixels from scratch (SolidColor, LinearGradient, RadialGradient, Plasma, Aurora, Swirl, Circle, noise patterns…). Very cheap.
   • Filter / effect components read pixels from below (Blur, Glow, Glass, GlassTiles, Dither, CursorTrail, etc.). When wrapped around children, they apply only to those children (a "nesting boundary").
4. Sibling order = paint order. Nesting = scope of effect.

<Shader className="w-full h-64">
  <LinearGradient colorA="#0f172a" colorB="#7c3aed" />  {/* bottom layer */}
  <GlassTiles>                                          {/* filter applied only to Circle */}
    <Circle color="#ff0088" radius={0.8} />
  </GlassTiles>
</Shader>

5. Props are reactive and cheap. Changing a prop writes a GPU uniform — no recompile, no flicker. Bind them to useState, scroll position, motion values, anything.
6. WebGPU first, WebGL2 fallback. The browser handles it; no setup required from you.

Install & import (React)

npm install shaders

import { Shader, LinearGradient, Aurora, Plasma, Swirl, CursorTrail, Glass } from 'shaders/react'

All component names are PascalCase, all props are camelCase, and <Shader> is always the root.

Sizing & positioning

The <canvas> has no intrinsic size. Apply width/height via className or style on the <Shader> component itself — never target the inner canvas (the internal DOM structure may change).

<Shader className="w-full h-64" />            {/* explicit height */}
<Shader className="w-full aspect-video" />    {/* fluid with aspect */}
<Shader className="fixed inset-0 -z-10" />    {/* full-page background */}
<Shader className="w-full h-[100dvh]" />      {/* mobile-safe viewport */}

For shader-as-background patterns (full page, section, card), see react-recipes.md.

Composition primitives

1. Stacking (siblings)

Bottom → top in source order:

<Shader>
  <LinearGradient />
  <Circle color="#ff0088" radius={0.6} />
  <CursorTrail />
</Shader>

2. Nesting (scope a filter)

Wrap a filter around the children you want it to affect; siblings before/after are untouched:

<Shader>
  <LinearGradient />               {/* not affected */}
  <Blur radius={20}>
    <Circle color="#ff0088" />     {/* only this is blurred */}
  </Blur>
</Shader>

3. Blend, opacity, visibility (per-component props)

• blendMode (string, default "normal") — 20 modes: the CSS-familiar set (multiply, screen, overlay, difference, …) plus normal-oklab / normal-oklch. Full list in the components reference.
• opacity (0–1) — multiplies alpha before blending. Still renders the layer.
• visible={false} — fully excludes from composition. Zero GPU cost. Use this (not opacity={0}) when a layer exists only as a mask source.

4. Masking (id + maskSource)

Any component can drive the visibility of another. Give the source an id, reference it from maskSource, and pick a maskType (alpha default, alphaInverted, luminance, luminanceInverted). Layer order doesn't matter — the mask just needs to exist in the tree, usually with visible={false}.

<Shader>
  <Circle id="mask" radius={0.8} visible={false} />
  <LinearGradient maskSource="mask" />
</Shader>

Reactive props — bind anything

const [angle, setAngle] = useState(0)
return (
  <Shader className="w-full h-64">
    <LinearGradient colorA="#ff6b6b" colorB="#4ecdc4" angle={angle} />
  </Shader>
)

Every numeric / color / position prop is reactive. GPU updates are uniform writes — animate freely without performance worries.

Dynamic prop drivers (declarative animation)

Instead of useState + requestAnimationFrame, pass a driver config object as a prop value. The library runs the loop on the GPU. Four drivers:

<Shader className="w-full h-64">
  <LinearGradient colorA="#0f172a" colorB="#4f46e5" />
  <LensFlare
    center={{ type: 'mouse-position', smoothing: 0.1 }}
    intensity={{
      type: 'auto-animate',
      mode: 'ping-pong',
      outputMin: 0.4,
      outputMax: 1.0,
      speed: 0.6,
    }}
  />
</Shader>

Prefer dynamic prop drivers over manual requestAnimationFrame loops — fewer React re-renders, less code, the library handles cleanup.

Transforms (UV-space, not CSS)

The transform prop shifts how a component samples its own coordinate system. It is not a CSS transform on the canvas DOM node.

<LinearGradient transform={{ rotation: 45, scale: 1.5, offsetX: 0.2 }} />
<Swirl transform={{ offsetX: 0.3, edges: 'wrap' }} />  {/* tiles seamlessly */}

Edge modes when content shifts out of bounds: transparent (default), stretch, mirror, wrap.

A non-default transform triggers a render-to-texture (RTT) pass that persists for the lifetime of the component — keep it in mind if you toggle transforms on/off in animations.

Shape / SDF effects (Glass, Neon, Emboss…)

A handful of components are driven by a shape: they wrap a physically-based effect around an SDF outline. Pass a shape prop with a type and shape-specific params.

Built-in type values: circleSDF, ellipseSDF, polygonSDF, starSDF, flowerSDF, ringSDF, crossSDF, roundedRectSDF, vesicaSDF, crescentSDF, trapezoidSDF.

<Glass shape={{ type: 'circleSDF', radius: 0.35 }} />
<Neon  shape={{ type: 'starSDF', radius: 0.35, sides: 6, innerRatio: 0.45 }} />
<Emboss shape={{ type: 'roundedRectSDF', width: 0.4, height: 0.25, rounding: 0.06 }} />

Custom logo / SVG shape: requires a pre-generated SDF .bin file passed via shapeSdfUrl. The conversion lives inside the Shaders editor (Pro) or the Shaders MCP. Do not attempt to generate the .bin by hand — point the user at the editor or MCP and link Shape Effects.

Color space (Figma parity)

Default output is Display P3 linear (wide gamut). If the user is copying hex values from Figma / Sketch / Adobe XD, those tools work in sRGB and the colors will look off. Set the root:

<Shader colorSpace="srgb">
  <SolidColor color="#5b18ca" />
</Shader>

Note: this is the output color space. Many gradient components also expose their own colorSpace prop (linear, oklch, oklab, hsl, hsv, lch) that controls interpolation between color stops — orthogonal concept, both can be set.

SSR / Next.js (mandatory pattern)

Shaders requires a GPU and cannot run on the server. In Next.js, always wrap shader components as client-only.

App Router — option A ('use client')

// components/MyShader.jsx
'use client'
import { Shader, Aurora } from 'shaders/react'

export default function MyShader() {
  return (
    <Shader className="w-full h-64">
      <Aurora />
    </Shader>
  )
}

App Router — option B (next/dynamic, recommended for backgrounds)

import dynamic from 'next/dynamic'
const MyShader = dynamic(() => import('@/components/MyShader'), { ssr: false })

Use option B whenever the shader file should stay framework-agnostic, or when you want to guarantee the module never loads on the server (avoids hydration edge cases).

Plain React SSR (no Next.js)

Guard with a mounted state:

const [mounted, setMounted] = useState(false)
useEffect(() => setMounted(true), [])
if (!mounted) return null

Lifecycle — onReady

<Shader onReady={...}> fires once after the GPU has compiled the shader and the first frame is ready. Use it to fade the canvas in, hide a skeleton, or trigger a dependent animation:

const [visible, setVisible] = useState(false)
return (
  <Shader
    onReady={() => setVisible(true)}
    style={{ opacity: visible ? 1 : 0, transition: 'opacity 0.5s' }}
  >
    <Aurora />
  </Shader>
)

Performance budget

Generators are essentially free; cost comes from render-to-texture (RTT) passes — every nesting boundary where a filter wraps children adds one. Relative cost tiers:

What triggers RTT (one extra pass each):

• Any filter/effect component reading the layer below.
• A non-default transform.
• A layer used as maskSource.
• A map dynamic prop driver (one-time RTT on first use).

Practical rules:

1. Build the base with generators. A full-screen Plasma or LinearGradient is essentially free; stack expensive filters on top sparingly.
2. Don't nest filters deeply. Three flat sibling filters is cheaper than three nested ones.
3. Use visible={false} to truly exclude a layer. opacity={0} still renders it. A hidden mask source costs nothing extra beyond being read as a mask.
4. Animate runtime props, not compile-time props. A small set of props recompile the shader on change — the component reference flags them. Driving them from useState causes flashes.
5. Off-screen canvases auto-throttle. The library drops to ~1 fps when scrolled out of view — don't manually pause unless you need to.

Decorative shaders — disable pointer capture

Canvases capture all pointer events by default. For a decorative background, add pointer-events-none so clicks reach the content below. Interactive components like CursorTrail and CursorRipples listen on window, so they still work even with pointer-events: none.

<Shader className="fixed inset-0 -z-10 pointer-events-none">
  <Aurora />
</Shader>

Aesthetic discipline (avoid generic GPU slop)

The same <Plasma /> with default props ships on every "AI hero" landing page. Before reaching for a component, commit to a direction:

• Pick one extreme, then execute it precisely: brutally minimal, maximalist saturation chaos, retro-futuristic CRT, organic / aurora-like, editorial monochrome with one accent. Don't average.
• Choose colors deliberately. Sample from the user's brand palette or a hand-picked combo — never ship default Plasma purple-on-black. Set colorSpace="srgb" if matching Figma hex.
• One signature motion. A breathing intensity, a slow rotation, a cursor-following accent — pick one and tune it slowly. Layering five auto-animations cancels into mush.
• Restraint reads as premium. A 1-component shader (single Aurora with a brand-tinted palette) usually beats a 5-layer composition. Add layers only when each one earns its presence.
• Respect motion preferences. Wrap shader-heavy hero sections in a prefers-reduced-motion check and drop to a static gradient if the user opted out.

const reduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches
return reduced
  ? <div className="w-full h-64 bg-gradient-to-br from-slate-900 to-violet-700" />
  : <Shader className="w-full h-64"><Aurora speed={3} /></Shader>

Workflow when adding a shader to a React/Next project

1. Confirm the framework and styling (Next.js App/Pages Router, Vite, plain React; Tailwind or plain CSS). If Next.js, lock in the SSR pattern before writing the component.
2. Commit to one aesthetic direction. Ask for brand colors and the shader's role (background, hero, decorative accent, interactive surface).
3. Pick one or two components from the components reference. Start with a generator as the base; add filters / masks only if the design requires them.
4. Wire sizing on <Shader>; add pointer-events-none if decorative.
5. Bind one prop to state or a dynamic prop driver if interactivity is required.
6. Test in the browser and watch the console for compile warnings on the first frame.
7. Audit performance: count RTT-causing layers (filters, masks, transforms, map drivers). If you have 3+, see if a flat composition gives the same look.
8. Respect prefers-reduced-motion with a static fallback before shipping.

For copy-pasteable React/Next.js patterns (full-page background, section background, card fill, mask reveal, scroll-linked, cursor-driven, SSR-safe loader), see react-recipes.md.

Reference map

• Full guide and component reference: shaders.com/docs/guide and shaders.com/docs/components.
• Composition rules: Composing Effects, Blending & Masking.
• Reactivity: Props & Reactivity, Dynamic Props, Transforms.
• Shapes: Shape / SDF Effects.
• Performance: Performance. Color: Color Space.
• SSR: Next.js / SSR. Lifecycle: Hooks & Events.
• Pro MCP server (optional, lets the agent browse / install presets and generate SDFs from SVGs): Shaders MCP.