Shaders

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> 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
    => setVisible(true)}
    style={{ opacity: visible ? 1 : 0, transition: 'opacity 0.5s' }}
  >
    <Aurora />
  </Shader>
)

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

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>