Skip to content

background · WebGL

ParticleField

A field of sparks drifting behind your content that moves aside for the pointer.

WebGL2 vertex-shader particle drift with pointer repel

  • WebGL
  • Reduced motion: static
  • 2.54 KB gzip
  • 1 WebGL context
  • Layout shift 0.0002
View the source Spec sheet as Markdown

Install

Install
pnpm dlx shadcn@4.21.1 add @frictionborn/particle-field

Playground

Palette
Your code
import { ParticleField } from "@/components/ui/particle-field";

<ParticleField />

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. Particle twinkle runs at about 0.3 Hz (sin(phase + time * 1.8) in the vertex shader), well below 3 flashes per second. There is no built-in pause button: pause with the paused prop or the runtime pauseAll()/resumeAll(). The optional scrim lowers background luminance 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: No pointer listeners are attached when the device does not report pointer: fine. Coarse pointers with low-end hints get the tier 1 poster; other coarse-pointer devices run the drift at tier 2.
  • WCAG criteria it is built for: 2.2.2, 2.3.1

Props

PropTypeDefaultWhat it does
colorstring"var(--primary, CanvasText)"Particle CSS colour, resolved from CSS variables or theme tokens and also used for the dot-pattern poster.
speednumber1Kinematic drift rate multiplier.
countnumber2000Target particle count on Tier 3 (clamped to 4,000). Tier 2 renders 35% of it.
interactivebooleantrueEnables pointer repulsion; only active when the device reports pointer: fine.
scrimbooleanfalseRenders a vertical gradient of the host --background token (40% to 75% opacity) over the canvas to lower background luminance behind children. Does not guarantee text contrast; verify for your colours.
pausedbooleanfalseFreezes this instance's particle loop. The global pauseAll() also stops it.
maxTiernumber3Upper bound on the capability tier (0 to 3); the tier is the minimum of this and the runtime tier.
reducedMotionbooleannoneOptional. 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.
classNamestring""Extra classes on the root div (the built-in class fb-particle-field is kept).
styleReact.CSSPropertiesnoneOptional. No default. Inline styles on the root div, merged after the built-in layout and background (consumer wins).
refReact.Ref<HTMLDivElement>noneReceives the root <div> that holds the poster and the canvas.
childrenReact.ReactNodenoneOptional. No default. Content layered above the poster, canvas and scrim.
palette"fire" | "ice" | "neon" | "mono" | "custom"noneColours from a palette (DESIGN.md A8): fire, ice, neon, mono, or custom (reads --fb-heat-0..4). Overrides color; 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.

MeasureResult
Size, gzip2.54 KB at load, 3.48 KB loaded later
Layout shift0.0002
Frames when nothing should moveoff screen 0, hidden tab 0, reduced motion 0
axe accessibility scan0 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.

EnvironmentTierResultDateNotes
Chromium Desktop (SwiftShader)3pass2026-10-2120 passed, 0 failed
Chromium Mobile (Pixel 7 emulation)2pass2026-10-2119 passed, 0 failed
Firefox Desktop3pass2026-10-2117 passed, 0 failed
WebKit Desktop3pass2026-10-2117 passed, 0 failed
WebKit Mobile (iPhone 14 emulation)2pass2026-10-2117 passed, 0 failed

On different devices

Reduced motion (static): Renders the static CSS dot-pattern poster with no WebGL context and no animation frames. Under prefers-reduced-motion the runtime tier is 0, so WebGL does not start.

TierWhat it does
T3 FullWebGL2 at DPR <= 2.0 with `count` particles, up to 4,000 (fine pointer with hover, no low-end hints)
T2 StandardWebGL2 at DPR <= 1.5 with 35% of `count` particles (coarse pointer without low-end hints, or fine pointer with low-end hints or viewport < 480px)
T1 LiteCSS dot-pattern poster only (coarse pointer with low-end hints: deviceMemory <= 2 or <= 4 cores)
T0 StaticCSS dot-pattern 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 style attributes, so allow style-src-attr 'unsafe-inline'.

Goes well with