API reference

createParticleFlow(canvas, options)

Creates one real-time particle field and returns ParticleFlowController.

createParticleFlow(
  canvas: HTMLCanvasElement | string,
  options?: ParticleFlowOptions,
): ParticleFlowController

Particle options

ParticleMode includes pulse, orbit, orb, wave, helix, vortex, constellation, scatter, lattice, ribbon, tunnel, stream, torus, rose, swarm, grid-wave, burst, and infinity.

ParticleShape includes circle, square, diamond, triangle, line, cross, ring, dash, star, and polygon.

Shape options

interface ParticleShapeOptions {
  rotation?: number;
  sides?: number;       // 3-12 for polygon
  fill?: boolean;
  strokeWidth?: number;
  aspect?: number;
}

Pointer interaction

interface ParticleInteractionOptions {
  mode?: "rotate" | "repel" | "attract";
  strength?: number;
  radius?: number;
  smoothing?: number;
}

Connections

interface ParticleConnectionsOptions {
  distance?: number;
  opacity?: number;
  width?: number;
  color?: string;
  maxPoints?: number;
}

Particle field

type ParticleField = (context: {
  index: number;
  count: number;
  time: number;
  seed: number;
  parameters?: Readonly<Record<string, number>>;
}) => ParticlePoint;

ParticlePoint contains x, y, and z, plus optional size, opacity, numeric color index and rotation values.

Particle controller

interface ParticleFlowController {
  readonly canvas: HTMLCanvasElement;
  readonly playing: boolean;
  play(): void;
  pause(): void;
  render(time?: number): void;
  resize(): void;
  update(options: Partial<ParticleFlowOptions>): void;
  destroy(): void;
}

Particle utilities

• particleFields exposes the eighteen built-in field functions.
• particlePresets adds orbitMesh, petals, current, terrain, flare, and loop to the original presets.
• sampleParticleField(mode, context) samples a built-in or custom field without creating a canvas engine.
• mixParticleFields(from, to, amount) returns a field that interpolates two topologies.
• composeParticleTransforms(...transforms) builds a reusable sequential transform.
• particleTransforms provides scale(), twist(), ripple(), and limit() factories.

Transforms may return false to remove a point from the current frame. Custom renderers receive screenX, screenY, renderSize, and colorValue on the projected point.

flow(target, options)

Animates every resolved target and returns FlowControls.

flow(target: FlowTarget, options?: FlowOptions): FlowControls

Targets

type FlowTarget =
  | string
  | Element
  | Iterable<Element>
  | ArrayLike<Element>;

Options

Standard KeyframeAnimationOptions values are accepted too.

Transform shortcuts

FlowFrame supports native keyframe properties plus these typed shortcuts:

{
  x, y, z,
  scale, scaleX, scaleY,
  rotate, rotateX, rotateY,
  skewX, skewY,
  blur
}

Numeric translate and blur values use pixels. Numeric rotation and skew values use degrees. String values keep their unit.

createFlow(defaults)

Returns a scoped flow function with reusable defaults.

const brandFlow = createFlow({ duration: 700, fill: "both" });
brandFlow(".item", { preset: "smooth-rise" });

stagger(amount, options)

Returns a delay resolver. from accepts "first", "center", or "last". start adds an initial delay. ease transforms normalized distance.

timeline(steps, options)

Schedules several flows and returns one controller. See Timelines and control.

inView(target, animation, observerOptions)

Starts a flow when targets intersect. observerOptions accepts normal IntersectionObserverInit fields plus once.

Easing helpers

pixelEase(steps?: number, position?: "start" | "end"): string
spring(options?: SpringOptions): string

The easings object exports linear, out, inOut, snap, and spring values.

Presets

type PresetName =
  | "pixel-pop"
  | "pixel-slide-up"
  | "pixel-glitch"
  | "pixel-flip"
  | "smooth-rise"
  | "smooth-scale"
  | "smooth-blur-in"
  | "smooth-slide-left"
  | "smooth-slide-right"
  | "soft-spring"
  | "elastic-pop";

Use definePreset() for typed custom preset objects.