Build with Dots.

Installation

Install the core package in your React app. Use the equivalent command if your project runs pnpm, Yarn, or Bun.

npm install dots-swarm

For UI primitives, import dots-swarm/ui.css once in your app entry or Next.js root layout. Put interactive examples behind a "use client" boundary and give each swarm an explicit height.

@dots-swarm:registry=https://dotsui.dev/api/registry/
//dotsui.dev/api/registry/:_authToken=${DOTS_TOKEN}

npm install dots-swarm @dots-swarm/pro

Describe the behavior. Keep control.

The skill teaches your agent the package boundaries and integration patterns. A copied prompt brings the exact effect you picked. Use either, or both.

npx skills add hamza-al/dots-next --skill dotsui

Read only what the task needs. Visit the Skill page for live examples and ready-to-copy prompts.

Your first swarm.

Changing shape starts a morph. Keep the same component mounted so particles retain their positions and momentum.

1"use client";
2 
3import { useState } from "react";
4import { DotSwarm, type Shape } from "dots-swarm";
5 
6export default function FirstSwarm() {
7  const [shape, setShape] = useState<Shape>("cloud");
8 
9  return <>
10    <DotSwarm shape={shape} count={900} color="#eeeeee"
11      transitionDuration={1.4}
12      style={{ width: "100%", height: 320 }}
13      label={shape === "cloud" ? "Particle cloud" : "Check mark"} />
14    <button type="button" onClick={() =>
15      setShape(current => current === "cloud" ? "check" : "cloud")
16    }>
17      {shape === "cloud" ? "Make a check mark" : "Back to cloud"}
18    </button>

DotSwarm reference

Shape catalog

Need the raw coordinates? Import getShapePoints from dots-swarm/shapes. It takes a shape, particle count, and optional animation time in seconds.

Timed sequences

DotsSequence describes the journey as data: named shapes or UI scenes, individual clip lengths, transition paths, and appearance. Studio exports a short TypeScript module or JSON definition. The package owns the clock and the renderer owns the particles.

1"use client";
2import { useMemo } from "react";
3import { DotsSequence, DotsSequencePlayer } from "dots-swarm";
4 
5export function AssistantLoop() {
6  const sequence = useMemo(() => new DotsSequence([
7    { shape: "halo", duration: 4 },
8    { shape: "heart", duration: 6, color: "#ffa9bd",
9      transition: { duration: 1.4, path: "flow" } },
10    { shape: "check", duration: 3 },
11  ], { loop: true, defaults: { count: 1000, color: "#ffffff" } }), []);
12 
13  return <>
14    <DotsSequencePlayer sequence={sequence} animate style={{ height: 360 }} />
15    <button type="button" onClick={() => sequence.restart()}>Replay</button>
16  </>;
17}
18 
19// Playback API: sequence.play(), pause(), restart(), seek(seconds).

Clip duration includes its arriving transition. The remaining time holds the finished formation. Add animate to the player to keep its native motion running during the hold. Per-element fields include color, count, speed, dotSize, spread, interactive, background, and transition duration/path. Defaults apply wherever an element omits a field. Keep the sequence instance stable across renders, using useMemo per component instance. Share an instance only when you intentionally want consumers to share a playhead.

1"use client";
2import { useMemo } from "react";
3import { DotsSequence, useDotsSequence } from "dots-swarm";
4import { SwarmUI, SwarmButton } from "dots-swarm/ui";
5import "dots-swarm/ui.css";
6 
7const scene = { position: "absolute" as const, inset: 16,
8  display: "grid", placeItems: "center" };
9 
10export function Onboarding({ onContinue }: { onContinue: () => void }) {
11  const sequence = useMemo(() => new DotsSequence([
12    { element: "cloud", duration: 4 },
13    { element: "continue", duration: 6 },
14  ], { loop: false }), []);
15  const { element } = useDotsSequence(sequence);
16 
17  return <SwarmUI.Root active={element.element!} transition={false}
18    style={{ position: "relative", height: 320 }}>

useDotsSequence exposes the current element, index, elapsed clip time, total time, progress, and playing state. It shares one clock across consumers, stops when unmounted, respects reduced motion, and suspends in a hidden tab. The pure class is also available from dots-swarm/sequence, without importing React.

1const sequence = DotsSequence.fromJSON(definition);
2const json = JSON.stringify(sequence); // compact, serializable data
3 
4// Private Pro package: names resolve through the registry.
5import { proShapes } from "@dots-swarm/pro";
6<DotsSequencePlayer sequence={sequence} shapes={proShapes} />
7 
8// Only genuinely custom geometry needs a separate asset file.
9import assets from "./my-swarm.assets.json";
10<DotsSequencePlayer sequence={sequence} assets={assets} />

Core and Pro catalog shapes export by name. Imported SVG geometry is downloaded separately as an assets file, and the timeline refers to an asset key. Studio backup preserves editor settings for later import. Pro artwork lives in its private package, available from your account after purchase.

Keyframe choreography

SwarmSequence is included in the free core. Drive its progress from a slider, scrolling, requestAnimationFrame, or an animation library. Seeking backward retraces the same paths; no timer or GSAP dependency is required.

1"use client";
2 
3import { useState } from "react";
4import { SwarmSequence, type SwarmKeyframe } from "dots-swarm";
5 
6// Keep keyframes outside the component, or memoize them.
7const keyframes: SwarmKeyframe[] = [
8  { at: 0, shape: "cloud", density: 0.4, dispersion: 0.7 },
9  { at: 0.5, shape: "wire-sphere", density: 1, dispersion: 0,
10    color: "#b6a1ff", rotation: 0.5, scale: 1.1,
11    ease: "smooth", path: "flow", stagger: 0.2 },
12  { at: 1, shape: "check", color: "#ffffff", rotation: 0,
13    scale: 0.9, dotSize: 1.8, opacity: 1 },
14];
15 
16export default function Choreography() {
17  const [progress, setProgress] = useState(0);
18  return (

Keyframes start at 0 and end at 1, in strictly increasing order. Animate shape or custom points, color (#RGB or #RRGGBB), density (0–1), dispersion (0–2), turbulence (0–1), speed (turbulence frequency, 0–5), dotSize (0.2–6), opacity (0–1), scale (0.1–2), rotation (radians), and x/y position (normalized units). Omitted properties carry forward.

Each destination keyframe controls the arriving segment: ease is smooth, linear, or elastic; path is flow, direct, or scatter; stagger ranges from 0 to 0.8. Repeat a formation at a later position to hold it. Keep count fixed and animate density to fade particles without rebuilding the pool.

Add animate to keep native shape motion playing while progress stays still. paused freezes that clock, and animationSpeed controls its rate (0–5). A keyframe’s rainbow value (0–1) blends its color toward a smooth 14-second spectrum cycle. The live clock stops offscreen, in hidden tabs, and under reduced motion.

The renderer draws only when needed, pauses offscreen, and snaps between keyframe poses under reduced motion. For scroll experiences, provide a useful static layout when reduced motion is enabled. Studio exports named DotsSequence definitions; use SwarmSequence for multi-property keyframes authored in code.

Scroll & triggers

Use useSwarmScroll to drive progress, fire threshold callbacks, or bind a DotsSequence. Native sticky panels and optional proximity snapping keep wheel, touch, and keyboard scrolling in the browser. These are the APIs used by this site’s hero and shape chapters.

1"use client";
2import { useRef } from "react";
3import {
4  useSwarmScroll, useSwarmScrollSnap, SwarmScrollPin,
5  SwarmScrollStops, SwarmSequence, type SwarmKeyframe,
6} from "dots-swarm";
7 
8const frames: SwarmKeyframe[] = [
9  { at: 0, shape: "halo" },
10  { at: 0.25, shape: "halo" }, // hold the finished, animated shape
11  { at: 0.55, shape: "heart" }, // leave room for the morph
12  { at: 0.8, shape: "heart" },
13  { at: 1, shape: "check" },
14];
15 
16function ScrollStory() {
17  const section = useRef<HTMLElement>(null);
18  const { progress, scrollTo } = useSwarmScroll({

Start/end pairs align a target edge with a viewport edge. Edges accept top, center, bottom, or a fraction. Offset can be a function for responsive headers. Pass a container ref for an overflow scroller. Call refresh() after external layout changes; resizing and font loading refresh automatically. Pinning uses the parent’s height as its scroll distance. Snap markers match the default top/top to bottom/bottom range in a window scroller.

Set scrub to a number of seconds for softened catch-up, or true for direct progress. onEnter, onLeave, onEnterBack, and onLeaveBack follow boundary crossings. Triggers take an at threshold, onCross, optional direction (forward by default), and once. Keep a once-trigger object stable with useMemo. Triggers do not fire retroactively on mount.

1const triggers = useMemo(() => [{
2  at: 0.6,
3  direction: "forward" as const,
4  onCross: () => surface.current?.act(swarmActions.explode({ strength: 900 })),
5}], []);
6 
7useSwarmScroll({ target: section, triggers });

Pass sequence to take over its clock and seek from scroll progress. On disconnect, normal playback resumes if enabled. Use DotsSequencePlayer animate to keep formation motion alive even for a timeline created with autoplay disabled. System reduced motion disables scrubbing; stage buttons still select a destination. The renderer controls its own motion policy. Snapping defaults to proximity and does not intercept upward scrolling.

Maps & directions

15 navigation formations and 6 maneuver values. Keep NavigationSwarm mounted and update its instruction from your routing provider.

1"use client";
2 
3import { NavigationSwarm } from "dots-swarm";
4import type { NavigationInstruction } from "dots-swarm/navigation";
5 
6export function NextDirection({ instruction }: {
7  instruction: NavigationInstruction;
8}) {
9  return (
10    <NavigationSwarm
11      instruction={instruction}
12      units="metric"
13      style={{ width: "100%", height: 320 }}
14    />
15  );
16}
17 
18// Example instruction from your routing adapter:
19// { maneuver: "turn-left", distanceMeters: 200, roadName: "Highway 401" }

NavigationSwarm accepts the same visual controls as DotSwarm, except shape and points. It defaults to direct choreography and supplies an accessible instruction label. Use units="imperial" for feet and miles; distances are always supplied in meters.

Free includes the generic roundabout and exit-number text. Pro adds 76 advanced navigation shapes, including directional roundabouts, lanes, merges, ramps, rich map states, and transport. Load these by name through @dots-swarm/pro. The shape gallery includes an integration prompt for each one.

The pure dots-swarm/navigation entry exports shapeForInstruction, shapeForManeuver, instructionText, formatDistance, navigationGroups, and the typed registries. Map and transport symbols work directly through DotSwarm.

This is a visualization layer. Supply location, route calculations, traffic, and instructions from your own map or routing service. The gallery’s city, highway, and roundabout sequences use demo data.

Custom geometry

Pass an array of { x, y, z } points. Use roughly −1 to 1 for x and y; z controls apparent depth. Geometry is resampled to the requested count. Changing the points array morphs to the new formation.

1import { DotSwarm, type Point } from "dots-swarm";
2 
3// Normalized coordinates, centered around { x: 0, y: 0 }.
4// Use Studio's SVG importer to generate detailed geometry.
5const points: Point[] = Array.from({ length: 600 }, (_, i) => {
6  const angle = (i / 600) * Math.PI * 2;
7  return { x: Math.cos(angle) * 0.8, y: Math.sin(angle) * 0.8, z: 0 };
8});
9 
10<div style={{ width: 400, height: 400 }}>
11  <DotSwarm points={points} count={600} />
12</div>

The Studio’s SVG importer supports paths, circles, ellipses, rectangles, lines, and polygons, including group transforms. Outline mode follows their contours. Fill mode respects compound-path holes and fill rules. Convert text, symbols, masks, and clips into paths before importing. SVG files are processed entirely in your browser.

UI primitives

Import working controls from dots-swarm/ui. Button, Select, Slider, Checkbox, and Switch assemble from the same particle pool, then become solid DOM controls. The controls use Radix for focus, keyboard interaction, disabled states, and form behavior. These primitives are included in the free core package.

1"use client";
2import { useState } from "react";
3import { SwarmUI, SwarmButton, SwarmSwitch } from "dots-swarm/ui";
4import "dots-swarm/ui.css";
5 
6export function Settings() {
7  const [scene, setScene] = useState("button");
8  return (
9    <>
10      <SwarmUI.Root active={scene} style={{ height: 260 }}>
11        <SwarmUI.Scene name="button" style={{ position: "absolute", inset: 80 }}>
12          <SwarmButton onClick={() => setScene("settings")}>
13            Open settings
14          </SwarmButton>
15        </SwarmUI.Scene>
16        <SwarmUI.Scene name="settings" style={{ position: "absolute", inset: 80 }}>
17          <SwarmSwitch.Root aria-label="Notifications" defaultChecked>
18            <SwarmSwitch.Thumb />

Root owns the pool. Scene names a formation. Change active to morph. Inactive scenes stay mounted to preserve their values, but are hidden and inert. Use absolute or grid positioning to place scenes in the same space.

1// Part adds swarm behavior to your own Radix or shadcn component.
2// The child must forward its ref and spread received props onto its DOM node.
3<SwarmUI.Scene name="custom">
4  <SwarmUI.Part asChild radius={12}>
5    <YourButton onClick={save}>Save changes</YourButton>
6  </SwarmUI.Part>
7</SwarmUI.Scene>
8 
9// Or begin as a shape, then change Root's active scene to a UI scene.
10<SwarmUI.Scene name="cloud">
11  <SwarmUI.Part shape="cloud" style={{ width: 240, height: 240 }} />
12</SwarmUI.Scene>

All controls forward refs and accept their underlying Radix props. They also work without a swarm root. Add visible labels or accessible names as you would with any control. Avoid nesting a Part around a primitive that already registers its own parts.

Import dots-swarm/ui.css once for the default design and overlay presence lifecycle. Customize with className and style on each part, or set --swarm-ui-bg, --swarm-ui-fg,--swarm-ui-muted, and --swarm-ui-accent on your root. Portalled content lives outside the root, so apply theme tokens to Content or a common ancestor too.

Root accepts surface options such as count, color, paused, reducedMotion, colliders, spring, and damping. Set transition to false for a direct morph or pass burst options to customize the scatter. Its ref exposes act(), burst(), and refresh(). Prefer explicit actions when the return destination can change. Reduced motion reveals the finished controls immediately.

Forms, overlays & layout

The UI subpath includes inputs, forms, navigation, overlays, and layout primitives. Interactive compound components retain Radix’s API: Root, Trigger, Content, Portal, and the component-specific parts. Inputs and layout elements use native HTML props.

SwarmInput, SwarmTextarea, SwarmLabel, SwarmCard, SwarmBadge, SwarmSeparator, SwarmSkeleton, SwarmDialog, SwarmAlertDialog, SwarmPopover, SwarmDropdownMenu, SwarmContextMenu, SwarmTabs, SwarmAccordion, SwarmRadioGroup, SwarmToggle, SwarmToggleGroup, SwarmTooltip, SwarmProgress, SwarmScrollArea, SwarmToast, SwarmNavigationMenu, SwarmForm, SwarmTable.

1import { SwarmUI, SwarmLabel, SwarmInput, SwarmButton } from "dots-swarm/ui";
2import "dots-swarm/ui.css";
3 
4<SwarmUI.Root active="profile" style={{ minHeight: 300 }}>
5  <SwarmUI.Scene name="profile">
6    <form onSubmit={onSubmit}>
7      <SwarmLabel htmlFor="email">Email</SwarmLabel>
8      <SwarmInput id="email" name="email" type="email" required />
9      <SwarmButton type="submit">Save</SwarmButton>
10    </form>
11  </SwarmUI.Scene>
12</SwarmUI.Root>

Every primitive works outside a swarm. Inside a scene, controls register their surfaces automatically. SwarmCard.Root registers the entire card as one material, including its background and content. Nested controls stay functional but do not compete for the same particle pool. For your own composite block, use SwarmUI.Part with contain and asChild. Tables remain layout containers until you wrap them in a Part.

Use Portal/Overlay/Content for dialogs and provide Title and Description. Retain accessible labels for inputs, sliders, and icon-only buttons. Components do not infer application labels. The built-in overlays manage their own local particle entrance and exit, including inside portals. Use a viewport surface when you deliberately want particles to travel across the page. Theme with --swarm-ui-bg, --swarm-ui-fg, --swarm-ui-border, --swarm-ui-accent, and --swarm-ui-muted. Add those tokens to portal content or a document-level theme as needed.

Component state changes

Button feedback and layout changes can use the same particle handoff as a scene change. SwarmMorph wraps one ref-forwarding element and animates when its state key changes. It retains keyboard focus and does not delay application state updates.

1import { SwarmButton, SwarmMorph, SwarmCard } from "dots-swarm/ui";
2 
3// saveState and saveProject come from your real submit handler.
4<SwarmButton morphKey={saveState} onClick={saveProject}
5  disabled={saveState === "pending"}>
6  {saveState === "saved" ? "Saved ✓" : saveState === "pending" ? "Saving…" : "Save project"}
7</SwarmButton>
8 
9<SwarmMorph state={selectedTab}>
10  <SwarmCard.Root>{/* your changing content */}</SwarmCard.Root>
11</SwarmMorph>

Select, dropdown-menu, context-menu, popover, and dialog content animate their own particle entrance and exit, including when rendered in portals. Radix continues to own focus, keyboard behavior, and dismissal. Dialog scrims fade in and out; the panel itself assembles from particles. Import ui.css for the presence lifecycle. Reduced motion skips the particle handoff. Scrolling the page or resizing cancels a transient handoff rather than leaving particles behind at stale positions.

Use morphKey or SwarmMorph for discrete changes, such as submitted → saved or one tab → another. Continuous editing—typing and dragging a slider—stays immediate. The primitive presets demonstrate these behaviors and include dialog and menu examples.

UI sequences

SwarmPrimitive supplies compact, editable defaults for thirteen common primitives. Compose their underlying parts directly for custom applications. Studio exports named UI definitions alongside your DotsSequence; no DOM coordinates are baked into it.

1import { DotsSequence } from "dots-swarm";
2import { DotsUISequencePlayer } from "dots-swarm/ui";
3import "dots-swarm/ui.css";
4 
5const sequence = new DotsSequence([
6  { shape: "cloud", duration: 3 },
7  { element: "welcome", duration: 7 },
8  { shape: "halo", duration: 3 },
9]);
10const elements = {
11  welcome: { kind: "card", label: "Your next idea", detail: "Make a little room." },
12} as const;
13<DotsUISequencePlayer sequence={sequence} elements={elements} />;

DotsUISequencePlayer handles mixed UI and shape sequences. Shape-only sequences can continue using DotsSequencePlayer. Named shapes and registered custom point motion stay animated in the mixed player. SwarmComposition offers the same surface with an externally controlled active scene. For a custom compound component, contain prevents duplicate registration of its child surfaces.

1<SwarmUI.Part contain asChild radius={12}>
2  <YourCard>{/* real inputs, labels, and buttons */}</YourCard>
3</SwarmUI.Part>

For the Studio sequence JSON export, download its elements JSON companion. The TypeScript export includes both objects. The Studio backup includes the full editable project.

Measure once. Form in place.

SwarmSurface keeps one particle pool across formations, falling motion, and real HTML elements. Give each target a stable ID and an element ref. The swarm measures its position inside the surface and springs into place.

1"use client";
2import { useMemo, useRef, useState } from "react";
3import { SwarmSurface, type SwarmTarget } from "dots-swarm";
4 
5export function LivingButton() {
6  const shape = useRef<HTMLDivElement>(null);
7  const button = useRef<HTMLButtonElement>(null);
8  const [gathered, setGathered] = useState(false);
9  const targets = useMemo<SwarmTarget[]>(() => gathered
10    ? [{ id: "button", kind: "element", ref: button, radius: 28 }]
11    : [{ id: "shape", kind: "shape", shape: "helix", ref: shape }],
12    [gathered]);
13 
14  return (
15    <SwarmSurface targets={targets} count={900}
16      style={{ height: 400, color: "white", background: "black" }}>
17      <div ref={shape} style={{ height: 280 }} aria-hidden="true" />
18      <button ref={button} onClick={() => setGathered(!gathered)}

Use multiple targets to split the swarm. Optional weight sets each target’s share of the fixed particle count. Targets support shape (core formations), points (custom normalized geometry), element (your actual HTML component), and avatar. Elements and avatars default to appearance: "solid". Particles fill the body as they gather, then disappear into a seamless finish.

Solid elements reveal their real DOM, so your fills, typography, borders, shadows, focus rings, and hover styles remain exactly as authored. Style the element normally. The surface temporarily controls its inline opacity and restores it when the target leaves or the surface unmounts. Avoid a separate CSS opacity transition on that element. Use appearance: "dots" for the original particle treatment; element targets then use radius and thicknessto form a dotted border. Optional target color colors the particles and solid avatars.

Keep the surface mounted. Resizing and font loading refresh its measurements. Call the ref’s refresh() after position-only layout changes or scrolling inside a nested container. Refs must point to elements inside the surface. Target and collider geometry should be untransformed; animate particle positions through targets rather than CSS transforms on the canvas.

The canvas is decorative and ignores pointer events. Your buttons, links, labels, focus management, and click handlers stay real HTML. The component does not automatically make a target interactive.

Explode. Rain. Reform somewhere else.

A target describes where the dots belong. An action changes what happens to the existing particles. Explode and rain leave the dots under physics. Reform is independent: the next destination can be a different avatar expression, a shape, or a real button.

1import { useRef } from "react";
2import { SwarmSurface, swarmActions, type SwarmSurfaceHandle } from "dots-swarm";
3 
4// Inside your component, with these refs attached to your surface and targets:
5const surface = useRef<SwarmSurfaceHandle>(null);
6const avatar = useRef<HTMLDivElement>(null);
7const button = useRef<HTMLButtonElement>(null);
8 
9// Each function can be a separate click or scroll handler.
10const explode = () => surface.current?.act(swarmActions.explode({
11  anticipation: 1.5, strength: 1800, spread: 0.95,
12  gravity: 170, duration: 2.7,
13}));
14 
15const becomeButton = () => surface.current?.act(swarmActions.reform({
16  duration: 2,
17  targets: [{ id: "continue", ref: button, kind: "element", radius: 24 }],
18}));

Use act() on a SwarmSurface or SwarmUI.Root ref. Colliders, viewport mode, pause, and reduced motion apply to actions. A new action replaces the previous one while retaining particle positions and velocities. Explicit reform targets remain active until the declarative targets prop changes.

1<SwarmSurface ref={surface} targets={targets} colliders={colliders}
2  viewport
3  onActionPhaseChange={(phase, action) => {
4    // charging → scattered, or gathering → settled
5  }}
6  onActionComplete={(action) => {
7    if (action.type === "explode") {
8      surface.current?.act(swarmActions.reform({
9        duration: 4.2,
10        targets: [{ id: "friend", ref: avatar, kind: "avatar",
11          expression: "dizzy", appearance: "solid" }],
12      }));
13    }
14  }}>
15  <div ref={avatar} style={{ width: 240, height: 240 }} />
16</SwarmSurface>

Explosion duration is the time after release until a completion cue fires; it does not reassemble the particles. Rain has no cue unless a duration is supplied. Reform ramps attraction over its duration and completes upon arrival. To use another UI scene, update SwarmUI.Root active and call reform; set transition={false} when actions own the transition. The older burst() method retains its automatic return.

Physics & text collisions

Switch to mode="physics" to release the particles, then return to mode="form" to gather them. Position and velocity carry through both modes. For event-driven releases, prefer rain and reform actions. Physics is a live simulation; scrubbing a scroll position does not replay a recorded trajectory.

1const surface = useRef<SwarmSurfaceHandle>(null);
2const headline = useRef<HTMLHeadingElement>(null);
3const colliders = useMemo(() => [
4  { ref: headline, kind: "text" as const }
5], []);
6 
7<SwarmSurface ref={surface} targets={targets}
8  colliders={colliders} gravity={460} wind={28} restitution={0.64}>
9  <h1 ref={headline}>Small dots. Big possibilities.</h1>
10  {/* Your measured targets and other real UI. */}
11</SwarmSurface>
12 
13// Connect these to separate application events or click handlers.
14const letItRain = () => surface.current?.act(
15  swarmActions.rain({ gravity: 460, wind: 28 })
16);
17const gather = () => surface.current?.act(
18  swarmActions.reform({ duration: 2 })
19);

Text colliders rasterize the actual glyphs, including wrapped lines; box colliders use rectangular bounds. The solver sub-steps and sweeps particles against those masks, then reflects their velocity. It supports gravity, horizontal wind, damping, springs, and boundary bounce. The core solver does not simulate dot-to-dot collisions or rigid-body rotation. Pro adds optional particle collisions and force fields. Neither solver reproduces arbitrary DOM artwork as a rigid body. Text masks support horizontal text without CSS transforms; remeasure after changing its content.

For your own renderer, import SwarmPhysics and createRectCollider from dots-swarm/physics. The solver has no React or DOM dependency. The root export also supplies createTextCollider and sampleSurfaceGeometry for browser-based renderers.

Core avatars

1const avatar = useRef<HTMLDivElement>(null);
2const targets = useMemo<SwarmTarget[]>(() => [{
3  id: "assistant", ref: avatar, kind: "avatar",
4  appearance: "solid",
5  expression: "curious", // also: neutral, happy, surprised, excited, dizzy
6}], []);
7 
8<SwarmSurface targets={targets} count={1800} color="#b9d4ff">
9  <div ref={avatar} style={{ height: 360 }} aria-hidden="true" />
10  <p>Your assistant is ready.</p>
11</SwarmSurface>

Solid avatars have a flat, softly lit body and large pill eyes. They breathe, blink, and glance toward the pointer. Use swarmActions.explode() to scatter the body and a separate reform() action to gather it again. Update expression to change their mood: excited opens the eyes; dizzy adds a sway and wandering eyes. Set the returning expression before calling reform, for example from onActionComplete. Pro’s SwarmAvatar adds adjustable silhouettes, eyes, and speech amplitude. Reduced motion makes them still. Keep meaningful assistant status in visible text as well.

Viewport effects

Add viewport to let particles leave their component and bounce off the page’s text and controls. The canvas passes clicks through to your UI. Selectors measure visible obstacles across the document; the target stays anchored to its original element.

1<SwarmSurface ref={surface} viewport targets={targets}
2  colliders={[
3    { selector: "h1, h2", kind: "text" },
4    { selector: "header a, button", kind: "box" },
5  ]}
6  gravity={170} restitution={0.82}
7  onActionComplete={action => {
8    if (action.type === "explode") {
9      setExpression("dizzy");
10      surface.current?.act(swarmActions.reform({ duration: 4.2 }));
11    }
12  }}>
13  <div ref={avatar} style={{ height: 400 }} aria-hidden="true" />
14</SwarmSurface>
15 
16// On click: build tension, then release.
17surface.current?.act(swarmActions.explode({
18  anticipation: 2.1, strength: 1900, spread: 0.95,

onActionPhaseChange receives charging, scattered, gathering, then settled once the particles arrive. The sequence follows the surface’s clock, including pause, visibility, and reduced motion. Action coordinates are viewport CSS pixels in this mode; omit them to explode from the particle centroid. Keep colliders stable and narrowly scoped to the UI the particles should hit. Use separate actions when the return destination or timing depends on your application.

Pro coordination systems

The private Pro package supplies timeline, event, transition, formation, physics, interaction, and avatar modules. Core remains the renderer and primitive layer. Pro + Studio is $149 USD once. Install it with npm using the private registry setup. Create your install token in your account after purchase. The showcases are open to everyone.

Multi-track timelines

1import { DotsTimeline } from "@dots-swarm/pro/timeline";
2import { DotsTimelinePlayer, useDotsTimeline } from "@dots-swarm/pro/react";
3 
4const timeline = new DotsTimeline({
5  version: 1, duration: 8, loop: false,
6  labels: { success: 5, retry: 0 },
7  tracks: [{ id: "main", clips: [
8    { id: "a", at: 0, duration: 5, value: { shape: "cloud" } },
9    { id: "b", at: 4, duration: 4, value: { shape: "check" } },
10  ] }],
11  gates: [{ at: 4, event: "result", branches: { ok: "success", error: "retry" } }],
12  cues: [{ at: 2, event: "action", payload: {
13    target: "avatar", action: { type: "explode", strength: 900 },
14  } }],
15});
16 
17// In an effect: timeline.play(); return () => timeline.pause();
18<DotsTimelinePlayer timeline={timeline} surfaces={{ avatar: avatarRef }} />

Tracks have stable IDs; clips carry at, duration, and a value object. The supplied player renders named shape tracks and blends two overlapping clips in one pool per track. Register Pro artwork with its shapes prop. For UI or other custom value types, use useDotsTimeline and map the sampled tracks to your component props. Cues execute during forward playback; seeking samples state without replaying side effects. Action cue targets refer to the player’s named surface refs. Reform destinations that contain DOM refs should be resolved in your own event handler, not serialized into JSON.

play, pause, restart, seek, emit, sample, subscribe, and toJSON are available. Multiple consumers share one clock. Gates suspend progression until their event arrives; branch values map to named labels. Reduced motion disables automatic playback in the React hook. Large frame gaps are clamped; this is an animation timeline, not a wall-clock scheduler.

Event graphs

1import { DotsEventGraph } from "@dots-swarm/pro/events";
2const graph = new DotsEventGraph({ version: 1, nodes: [{
3  id: "open", event: "click", delay: 0.2, reentry: "replace",
4  commands: [{ target: "panel", method: "open" }], emit: "opened",
5}] });
6const unregister = graph.register("panel", async (method, value, signal) => {
7  if (signal.aborted) return;
8  if (method === "open") openPanel();
9});
10graph.emit("click");
11// Cleanup: unregister(); graph.dispose();

Nodes connect an event to registered commands, then optionally emit another event. Reentry can replace pending runs, ignore repeats, or allow parallel runs. Delays are cancellable; async handlers receive an AbortSignal and must cooperate with cancellation. Graph cycles stop within one dispatch chain. Unknown target handlers report errors rather than evaluating arbitrary code. Use cancel(nodeId) or cancel() for pending runs.

UI flows

1import { SwarmFlow, useSwarmFlow } from "@dots-swarm/pro/react";
2 
3<SwarmFlow initial="button">
4  <SwarmUI.Scene name="button"><Launcher /></SwarmUI.Scene>
5  <SwarmUI.Scene name="settings"><SettingsForm /></SwarmUI.Scene>
6</SwarmFlow>
7 
8// Inside Launcher:
9const { go, active, busy } = useSwarmFlow();
10<SwarmButton onClick={() => go("settings")}>Open settings</SwarmButton>

A flow explicitly explodes, changes its active scene, then reforms. New destinations replace pending ones during interruption. Scene state stays mounted and the core scene layer handles focus leaving inactive content. Layouts and their content remain your React components.

Formations and transitions

1import { createFormation } from "@dots-swarm/pro/formations";
2import { transitionPoints, partitionPoints } from "@dots-swarm/pro/transitions";
3const ribbon = createFormation({ kind: "ribbon", turns: 3, twist: 2,
4  thickness: 0.18, count: 1200, time });
5const destination = partitionPoints([
6  { points: heart, x: -0.5, scale: 0.45 },
7  { points: check, x: 0.5, scale: 0.45 },
8], 1200);
9const points = transitionPoints(ribbon, destination, progress, {
10  wave: "radial", stagger: 0.3,
11  path: [{ x: 0, y: 0, z: 0 }, { x: 0, y: -0.6, z: 0.4 }, { x: 0, y: 0, z: 0 }],
12});
13<DotSwarm points={points} transitionDuration={0} />

Formations support rings, ribbon, and knot families with count, radius, thickness, turns, twist, and time. Transitions are stateless and seekable. Paths specify piecewise-linear normalized offsets with a zero envelope at either endpoint. Waves use x, y, or radial ordering; a custom mask callback can supply per-particle order. Partitions preserve index ranges when group order and weights stay fixed.

Physics and gestures

1import { ProSwarmPhysics, circleCollider, polygonCollider } from "@dots-swarm/pro/physics";
2import { useSwarmGesture } from "@dots-swarm/pro/interactions";
3const { field, gesture } = useSwarmGesture(containerRef, { mode: "vortex" });
4const createPhysics = useCallback(points => new ProSwarmPhysics(points, () => ({
5  fields: field.current ? [field.current] : [],
6  collisions: true, particleRadius: 2,
7  colliders: [circleCollider(movingX.current, 250, 30)],
8  constraints: [{ index: 0, x: 200, y: 80, length: 50, stiffness: 0.8 }],
9})), [field]);
10<SwarmSurface createPhysics={createPhysics} targets={targets} />

The solver reads configuration each step, so fields, obstacles, and constraint anchors can move. Fields attract, repel, or create vortices. Optional particle collisions use a spatial grid; keep particle counts modest when enabling them. Constraints attach particle indices to an anchor or maximum distance. Solver coordinates are local CSS pixels, or viewport pixels for viewport surfaces. Keep the factory stable and read changing values through refs to preserve the particle pool. For example, read a moving collider’s position from a ref inside the config getter rather than capturing a stale render value.

useSwarmGesture provides pointer capture, drag offsets, two-pointer scale/rotation, and a mutable field ref. It temporarily owns touch-action on its target, restoring it on cleanup; attach it to the interactive stage rather than the whole page. Gestures report values—the application chooses how to map scale or rotation to its elements.

Avatars

1import { SwarmAvatar } from "@dots-swarm/pro/avatar";
2<SwarmAvatar ref={surface} silhouette="squircle" expression="curious"
3  eyeScale={1.3} eyeSpacing={0.3} color="#78adff"
4  speech={normalizedAudioLevel} style={{ height: 320 }} />

Silhouettes are orb, squircle, and pebble. Eye size, spacing, body and eye colors are configurable. Six expressions blend their eye/pose parameters; speech (0–1) drives mouth movement alongside the expression. The component accepts the surface action ref and physics props. It does not record audio or connect a speech service. Supply amplitude from your own audio pipeline. createAvatarRenderer is available for custom targets through the core renderer extension.

Composition Studio

Studio mixes shapes and real UI primitives in one timeline. Use the UI library beside Presets and Shapes, then edit the label and description in the inspector. SVG import and existing shape presets remain available. Save a Studio backup to retain UI definitions and timeline settings together. Advanced choreography adds overlapping tracks, wait gates, avatar action cues, and editable event connections. Projects and graphs can be saved locally, imported, and exported as JSON. Public showcases are separate experiences, with compact API examples rather than editor controls.

Timeline JSON is loaded with DotsTimeline.fromJSON; event JSON is passed to DotsEventGraph. Register event handlers and named surface refs in your app. Advanced local save stores the timeline and graph together. Main Studio keeps its own presets and draft. Use Save to cloud and Open from cloud for private projects tied to your Pro account, or share exported files to move work between devices. Shared editing and collaboration are not included.

Studio exports & agent handoff

Arrange up to 12 formations, customize motion and color, then copy an agent prompt or export a compact DotsSequence module or JSON definition. A separate Studio backup preserves editor settings for later import.

The MIT core includes everyday assistant, calendar, messaging, media, commerce, and data/security essentials. The Pro collection adds 118 formations across assistant, productivity, communication, media, commerce, data/security, and abstract sculpture families, plus 7 editable sequences. Pro + Studio costs $149 USD as a one-time purchase, with permanent access and future updates included.

Pro artwork is separate from the MIT core package. Choose a Pro shape or recipe in Studio and its export refers to a named shape from @dots-swarm/pro. Only custom SVG artwork needs a separate geometry asset. Sculptures retain rotation, swirl, wave, pulse, or orbit motion through the registry.

Drafts and local presets stay in this browser. Use Save to cloud in either Studio workspace to keep projects in your account and open them on another device. JSON exports remain available for portable backups.

Accessible by design

Dots automatically respects prefers-reduced-motion, renders an immediate static pose, and disables pointer forces. It suspends animation outside the viewport and while the page is hidden.

Use a meaningful label, visible text for important status, and an accessible pause control for persistent animation. Don’t communicate a critical event through particles alone.