Skip to content

Conventions

Learn one component, know them all

The same prop names, the same units and the same escape hatches on all 25 components, so neither you nor your agent has to guess.

Units

PropType and unitRule
durationnumber (ms)Always milliseconds: duration={1200} is 1.2 seconds.
speednumber (multiplier)1 is the component's normal speed; 0.5 is half, 2 is double.
pixelsPerSecondnumber (px/s)Drift in pixels per second (Marquee).
strengthnumber (0 to 1)How strong an effect is, clamped between 0 and 1.
pullDistancenumber (px)The farthest a MagneticButton moves, in pixels.
pausedbooleanStops the component; present on all 25.

What paused does

Motion that runs longer than five seconds needs a way to stop it (WCAG 2.2.2). While paused is true a component asks for no animation frames at all; this is checked in a real browser for every component.

  • mesh-gradient, noise-field, particle-field: the frame loop stops; the last frame stays on screen and the WebGL context is kept.
  • distortion-image: gives its WebGL context back and shows the plain image.
  • smooth-scroll: removes the smooth scroll; the browser's own scrolling takes over.
  • marquee: stops the strip where it is (animation-play-state: paused).
  • text-reveal: shows the whole text at once.
  • scroll-reveal: shows the content in its final state.
  • the twelve canvas components (flame-switch, ember-badge, lantern-sky and the rest): the effect stops drawing and the last frame stays; the control itself (switch, tabs, slider, button) keeps working.

A component's paused stops that component only. To stop everything at once (a site-wide “Pause motion” button), call pauseAll() from @frictionborn/runtime; it stops the shared frame loop.

Refs, props and imports

Every component forwards ref to its root element and spreads the HTML attributes you pass onto it. Your handlers (onPointerMove, onFocus and so on) run alongside the component's own. Named and default exports both work:

Imports
import { AmbientHero } from "@/components/ui/ambient-hero";
// or
import AmbientHero from "@/components/ui/ambient-hero";

What next

See the units in action in any component playground, or read the performance budget each component is measured against.