Particle Field

Install

pnpm dlx shadcn@latest add @vegastack/particle-field

Usage

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

<div className="relative">
  <ParticleField seed={7} count={48} />
  <h1 className="relative">Ship agentic UI, fast.</h1>
</div>;

ParticleField is absolutely positioned to fill its parent (inset-0) — wrap it in a relative container and stack your real content above it (relative + normal document order, or z-*).

Examples

Lazy by construction

The draw/animate effect only starts once the element is intersecting the viewport and the browser reports idle (requestIdleCallback, falling back to setTimeout(0) where unsupported) — a hero hidden below the fold never spends a frame budget before it's visible. For true code-splitting (not loading the component's JS at all until needed), wrap the import at the call site in next/dynamic(() => import(...), { ssr: false }) — see the docs-home hero for the reference usage.

Determinism

The layout is deterministic per seed, so the same seed always paints the same field and a screenshot never drifts.

Reduced motion & theme

Renders exactly one static frame (no requestAnimationFrame loop at all) under prefers-reduced-motion: reduce, repainted when the theme changes so this branch follows the theme too. The particle ink is the canvas's own resolved color (it carries text-brand), read per frame rather than captured once at mount — so toggling light/dark recolours the field in place, with no remount. Particle positions come from a seeded PRNG (mulberry32) — never Math.random() — so the same seed always produces the same layout. count is capped (PARTICLE_FIELD_MAX_COUNT) regardless of the value passed, so it stays subtle and performant by construction. The root element carries data-drawn once the first frame has actually painted — wait on that attribute instead of guessing a delay (a VRT harness should).

API Reference

Accessibility

• Purely decorative — rendered aria-hidden="true" in full; it never carries content a screen reader needs.
• Respects prefers-reduced-motion: reduce by rendering one static frame — which still follows a theme change, so a reduced-motion user never sees the wrong-theme ink.

Do / Don't