@shader-gallery/react

React components for shader.gallery animated WebGL backgrounds. Two ways in: fetch a shader by slug from the CDN, or bundle one .frag with your app.

npm install @shader-gallery/react @shader-gallery/runtime

<ShaderGalleryBg> — fetch by slug

The default. Renders a <canvas> and drives the shader through @shader-gallery/runtime (a real React component, not a wrapper around the web component). The GLSL streams from the CDN by slug at runtime, so your bundle stays tiny and the catalog can update without a package release.

import { ShaderGalleryBg } from '@shader-gallery/react';

export function Hero() {
  return (
    <section style={{ position: 'relative', minHeight: '100vh' }}>
      <ShaderGalleryBg
        slug="nacre"
        palette="witchlight"
        style={{ position: 'fixed', inset: 0, zIndex: -1 }}
      />
      <h1>Backgrounds that glow in the dark</h1>
    </section>
  );
}

Override uniforms and post-FX by name. These retarget the running shader without rebuilding the WebGL context, so they are cheap to drive from state:

function Tunable() {
  const [glow, setGlow] = useState(1.0);
  return (
    <>
      <ShaderGalleryBg
        slug="nacre"
        palette="ember"
        uniforms={{ u_glow: glow }}
        post={{ bloom: 1.2, grain: 0.15 }}
        style={{ position: 'fixed', inset: 0 }}
      />
      <input type="range" min={0} max={2} step={0.01}
        value={glow} onChange={(e) => setGlow(+e.target.value)} />
    </>
  );
}

An inline uniforms/post object is a fresh reference each render and re-runs the apply effect. The write is cheap, but useMemo the object if you render very often.

Props

Prop	Type	Notes
slug	string	Which shader to load from the CDN.
palette	string	Theme name; defaults to the shader's own. Changes live.
base	string	Data source URL. Defaults to the production CDN; point at http://localhost:…/ or a Cloudflare tunnel during dev.
uniforms	Record<string, number>	Overrides over the shader's defaults, e.g. { u_glow: 1.4 }. Apply live.
post	Record<string, number>	Post-FX overrides, e.g. { bloom: 1.2 }. Apply live.
frag,meta	string, object	Provide the shader directly instead of fetching by slug (bundled/offline).
style,className, …	—	Forwarded to the canvas. Fills its parent by default.

palette, uniforms and post retarget the running shader without rebuilding the WebGL context; slug/base/frag remount.

shader() — bundle one frag

The complement to <ShaderGalleryBg>: instead of fetching by slug, this carries the GLSL with you (offline, versioned, tree-shaken). Each float param becomes a friendly prop (u_waveSpeed → waveSpeed); palette and post are universal.

A shader.gallery effect is one self-contained .frag with an embedded /*@shader … */ JSON header. Author your own, or copy the reference effect that @shader-gallery/components ships on disk at node_modules/@shader-gallery/components/effects/billow.frag (params waveSpeed / swell / cross).

import { shader } from '@shader-gallery/react';
import billowSrc from './billow.frag?raw';   // Vite/webpack raw import

const Billow = shader(billowSrc);

export function Background() {
  return (
    <Billow
      waveSpeed={0.6}
      swell={420}
      palette="opal"
      style={{ position: 'fixed', inset: 0 }}
    />
  );
}

Params apply live, same as uniforms above — wire one to state for a playground:

function Playground() {
  const [waveSpeed, setWaveSpeed] = useState(0.35);
  return (
    <>
      <Billow waveSpeed={waveSpeed} palette="midnight" style={{ position: 'fixed', inset: 0 }} />
      <input type="range" min={0} max={2} step={0.01}
        value={waveSpeed} onChange={(e) => setWaveSpeed(+e.target.value)} />
    </>
  );
}

./billow.frag?raw is the Vite/webpack way to import a file as a string. On a setup without raw imports, read the file to a string yourself (or in Node, the build step) and pass it to shader() — or use <ShaderGalleryBg frag={…} meta={…} />.

Typed params

shader() returns a loosely-typed component (per-param props are unknown). For autocomplete on waveSpeed/swell/cross, generate a per-effect .d.ts with sg-typegen (from @shader-gallery/components) and cast against it:

npx sg-typegen billow.frag --out billow.d.ts

import { shader } from '@shader-gallery/react';
import billowSrc from './billow.frag?raw';
import type { BillowProps } from './billow';

const Billow = shader(billowSrc) as (p: BillowProps) => JSX.Element;
<Billow waveSpeed={0.6} swell={420} cross={0.5} palette="opal" />;

SSR

Safe. The component renders a bare <canvas> on the server; the WebGL mount runs in a client-only effect.

MIT © E. T. Carter · shader.gallery · support@shader.gallery