Use physics when movement carries a data claim: a body is delayed, blocked, sorted, sampled, counted, or settled because of the data. If movement only makes a static chart feel active, use ordinary chart animation or no motion.
For process HOCs (Gauntlet vs ProcessFlow), capacity queues, body marks, and the example checklist, see thePhysics process guide.
Rule of thumb: every physics chart needs a settled projection that is still a useful chart when the animation is paused, skipped, or rendered for reduced motion.
Four Modes
Pick the mode before picking the component. Most confusion comes from putting texture-style particles on a layout chart and asking readers to infer meaning from motion that does not actually encode anything.
| Mode | Readout | Use it for | Semiotic starting point |
|---|
| Layout | Read at rest | Collision relaxation, swarms, piles, and packed bodies where motion is how the layout finds a stable position. | CollisionSwarmChart |
| Process | Read the transition and the result | The simulation mirrors the system being explained: sampling through bins, late-event barriers, backpressure, or settling into categories. | EventDropChart |
| Uncertainty | Read the settled distribution | Posterior samples or scenario draws fall through a process and rest as a quantile dotplot or histogram — motion frames frequency, not network topology. | GaltonBoardChart |
| Texture | Read the base chart | Particles decorate flow direction or activity. Keep this in the host chart unless the bodies carry data, collisions, or state. | Realtime Encoding |
Settled Projection
The accessible object is the settled or aggregated chart, not the path each body took. Motion may teach the process, but the chart still owes readers a stable answer: bins, totals, intervals, late counts, sediment, or an explicit projection table.
- Plinko Quantile Dotplotdrops posterior samples through a board, then reads the same tokens as a quantile dotplot.
- Watermarks, Made Physicalanimates event arrivals, then exposes settled window counts and late counts.
- PhysicsPileCharttreats bodies as unitized value carriers, then reads the piled result by category.
- CollisionSwarmChartuses collisions to separate overlapping dots while preserving their x-axis position.
- ProcessFlowChartmoves work items through capacitated stages and reads stage counts plus feature completion.
Displacement Ledger
A displacement ledger names what moves, why it moves, and what state change the movement represents. Write this before building a custom physics scene. If you cannot fill in displacement, projection, and accessibleReadout, the chart probably does not need physics.
JS
const displacementLedger = { source: "arrivalTime and eventTime", body: "one event body per row", displacement: "body falls into the event-time window bin", barrier: "watermark closes old windows", sensor: "late bodies cross into the late gutter", projection: "window totals and late counts", accessibleReadout: "settled table + live milestone observations", }
Motion Budget
Motion should clarify the state transition once, then get out of the way. Budget it the same way you budget labels and annotations: what does it cost, and what does the reader learn that the settled chart cannot show alone?
| Budget item | Requirement |
|---|
| Autoplay | Short enough to understand in one pass; provide pause and replay when motion continues. |
| Reduced motion | Render the settled projection first, then let users opt into replay where appropriate. |
| Time scale | Use replay time scale for arrival pacing, not to slow gravity or the physics clock. |
| Body count | Keep live bodies within a readable range; aggregate, evict, or sediment long streams. |
| Accessibility | Expose the settled chart, aggregate rows, and milestone observations as the accessible object. |
JSX
<EventDropChart data={events} timeAccessor="eventTime" arrivalAccessor="arrivalTime" windows={{ size: 12 }} watermark={{ delay: 18 }} timeScale={0.08} // replay pacing only paused={prefersReducedMotion} frameProps={{ onTick: (result, controls) => setRuntime(controls.snapshot()), onBodyPointerDown: (body) => setSelectedEvent(body?.datum), }} />
Choose The HOC
| Component | Use when | Settled projection |
|---|
| GaltonBoardChart | Posterior samples, uncertainty, binned outcomes, and Plinko-style explainers. | Histogram or quantile-dotplot projection. |
| EventDropChart | Event time versus arrival time, watermarks, lateness, queueing, and windows. | Window counts, late counts, and closed/open state. |
| PhysicsPileChart | Unitized counting, category bins, sedimented totals, and materialized denominators. | Category totals and represented value. |
| CollisionSwarmChart | Dot strips and grouped distributions where collisions reveal local density without hiding the quantitative axis. | X-axis distribution with optional group lanes and counts. |
| ProcessFlowChart | Multi-body workflows with capacitated stages, rework portals, and feature groups that complete only when every member is absorbed. | Stage occupancy counts and group completion ledger. |
| GauntletChart | One compound plan degraded by timed gate effects (lift balloons and drag particles). | Property inventory, viability, and outcome state. |
| PhysicalFlowChart | Packets on authored routes where throughput stays readable as a static layer. | Route throughput and node totals. |
| PhysicsCustomChart | The scene needs custom colliders, sensors, spawn rules, or overlays that the HOCs do not expose. | Your layout must return the projection evidence explicitly. |
Reach for PhysicsCustomChartonly after the HOCs fail on geometry or state. If the custom scene does not need colliders, sensors, spawn timing, or sediment, it is probably an ordinary custom chart.
Do Not Use Physics For
- Decorating a bar, line, or Sankey chart with particles that do not carry data.
- Replacing a readable axis, legend, or summary with a body path.
- Hiding uncertainty behind randomness without showing the sample or interval.
- Long-running streams that never aggregate, evict, sediment, or pause.
- Any chart where reduced motion would remove the only meaningful readout.