background · WebGL
MeshGradient
Soft colour drifting slowly behind a hero, with a still poster where motion is off.
multi-color organic mesh gradient via WebGL2
- WebGL
- Reduced motion: static
- 3.01 KB gzip
- 1 WebGL context
- Layout shift 0
Install
pnpm dlx shadcn@4.21.1 add @frictionborn/mesh-gradient
Playground
import { MeshGradient } from "@/components/ui/mesh-gradient";
<MeshGradient />In a full example
The full example loads as you scroll to it.
Accessibility
- The poster, scrim and canvas layers are aria-hidden; the root element and children are not. There is no built-in pause button: pause with the paused prop or the runtime pauseAll()/resumeAll(). The optional scrim lowers background luminance behind children but contrast is not computed; verify text contrast for your colours.
- Keyboard: None; the component has no interactive elements. Poster, scrim and canvas layers are aria-hidden; children keep their own semantics.
- Touch: None; no touch or pointer listeners. Coarse pointers with low-end hints get the tier 1 poster; other coarse-pointer devices run WebGL at tier 2.
- WCAG criteria it is built for: 2.2.2
Props
| Prop | Type | Default | What it does |
|---|---|---|---|
colors | string[] | ["var(--background, Canvas)","var(--primary, CanvasText)","var(--chart-1, var(--accent, GrayText))","var(--chart-2, var(--muted, ButtonFace))"] | CSS colours resolved from host tokens. Only the first four are used (extra entries are ignored); missing entries reuse earlier ones. The first colour is the background. |
speed | number | 1 | Unitless multiplier of the standard drift. 1 is the standard speed, which is already slow (0.35 shader seconds per second); 0.5 is half and 2 is double. |
distortion | number | 0.5 | Amplitude of organic noise distortion. |
swirl | number | 0.25 | Vortex swirl strength in the gradient field. |
grainMixer | number | 0.08 | Subtle analog grain distortion strength. |
grainOverlay | number | 0.04 | Post-processing fine film grain overlay intensity. |
scrim | boolean | false | Renders a radial scrim of the first colour (20% centre to 80% edge opacity) over the canvas to lower background luminance behind children. Does not guarantee text contrast; verify for your colours. |
paused | boolean | false | Freezes this instance's shader animation loop. The global pauseAll() also stops it. |
maxTier | number | 3 | Upper bound on the capability tier (0 to 3); the tier is the minimum of this and the runtime tier. |
reducedMotion | boolean | none | Optional. No default (follows prefers-reduced-motion). true forces the static poster. false only skips the prop-level check: under prefers-reduced-motion the runtime tier is still 0, so WebGL still does not start. Leave unset. |
className | string | "" | Extra classes on the root div (the built-in class fb-mesh-gradient is kept). |
style | React.CSSProperties | none | Optional. No default. Inline styles on the root div, merged after the built-in layout and background colour (consumer wins). |
ref | React.Ref<HTMLDivElement> | none | Receives the root <div> that holds the poster and the canvas. |
children | React.ReactNode | none | Optional. No default. Content layered above the poster, canvas and scrim. |
palette | "fire" | "ice" | "neon" | "mono" | "custom" | none | Colours from a palette (DESIGN.md A8): fire, ice, neon, mono, or custom (reads --fb-heat-0..4). Overrides colors; leave it out to keep the host's tokens. |
Measured on the bench
Measured by the automated bench at commit 801163e on 2026-10-21. These numbers are written by the bench, never by hand.
| Measure | Result |
|---|---|
| Size, gzip | 3.01 KB at load, 3.5 KB loaded later |
| Layout shift | 0 |
| Frames when nothing should move | off screen 0, hidden tab 0, reduced motion 0 |
| axe accessibility scan | 0 serious, 0 critical |
Browsers it ran in
Automated Playwright runs, some with device emulation. Results from physical phones and tablets are still pending, so none are listed.
| Environment | Tier | Result | Date | Notes |
|---|---|---|---|---|
| Chromium Desktop (SwiftShader) | 3 | pass | 2026-10-21 | 21 passed, 0 failed |
| Chromium Mobile (Pixel 7 emulation) | 2 | pass | 2026-10-21 | 20 passed, 0 failed |
| Firefox Desktop | 3 | pass | 2026-10-21 | 18 passed, 0 failed |
| WebKit Desktop | 3 | pass | 2026-10-21 | 18 passed, 0 failed |
| WebKit Mobile (iPhone 14 emulation) | 2 | pass | 2026-10-21 | 18 passed, 0 failed |
On different devices
Reduced motion (static): Renders the static CSS gradient poster with no WebGL context and no animation frames (Decision 14 D-A). Under prefers-reduced-motion the runtime tier is 0, so WebGL does not start.
| Tier | What it does |
|---|---|
| T3 Full | WebGL2 at DPR <= 2.0, full render scale, 4 octaves (fine pointer with hover, no low-end hints) |
| T2 Standard | WebGL2 at DPR <= 1.5, 0.75 render scale, 2 octaves (coarse pointer without low-end hints, or fine pointer with low-end hints or viewport < 480px) |
| T1 Lite | CSS multi-radial gradient poster only (coarse pointer with low-end hints: deviceMemory <= 2 or <= 4 cores) |
| T0 Static | CSS multi-radial gradient poster only, no WebGL (server render, prefers-reduced-motion, Save-Data, no WebGL2, or frame-guard downgrade) |
Content Security Policy
- Works without
'unsafe-eval'. - Needs no reveal gate.
- Sets inline
styleattributes, so allowstyle-src-attr 'unsafe-inline'.