Charts — Physics Custom Chart — Semiotic

Home · Getting Started · Charts · Features · Playground

This page requires JavaScript for interactive chart demos.

AI / Machine-readable docs: llms.txt · llms-full.txt · CLAUDE.md · schema.json · API Reference · Examples

View on GitHub · npx semiotic-ai for CLI access

Machine-readable page content

Canonical: https://semiotic.nteract.io/charts/physics-custom-chart

PhysicsCustomChart

charts

import { PhysicsCustomChart } from "semiotic/physics"

Wraps: StreamPhysicsFrame

PhysicsCustomChart is the physics equivalent of the custom-chart escape hatch. You still describe a chart in data terms, but the layout returns a physics scene: initial bodies, barriers, proximity sensors, observation metadata, and SVG overlays. It is useful when StreamPhysicsFrame is too low-level and the fixed physics HOCs are too specific.

Interactive routing demo

This demo owns a custom routing layout. Barriers create a chute and lane dividers. The translucent lane zones are sensors, so packets change state as they pass through each proximity gate.

Deflector

Launch speed1.0x

Physics custom routing demo

Simulation8live packets0 queued, moving, 0.00s

Last pushseed-008Shipaudit priority

SelectednoneClick a packetNo packet selected

Triage sensoridlenone at 0.00s - 0 enters

Review sensoridlenone at 0.00s - 0 enters

Ship sensoridlenone at 0.00s - 0 enters

Recent sensor events

No proximity events yet. Push a packet or run a burst.

Why not the base frame?

StreamPhysicsFrame is the right tool when your app already speaks physics primitives. PhysicsCustomChart is better when you want to publish a chart-shaped component: callers pass data, layout options, colors, click handlers, and realtime pushes while the layout function translates those rows into simulation bodies.

Fixed physics chart HOCs

Use GaltonBoardChart, EventDropChart, PhysicsPileChart, CollisionSwarmChart, or PhysicalFlowChart when their data model is already your chart.

StreamPhysicsFrame

Use the base frame when you already have low-level bodies, colliders, budgets, workers, and observations.

PhysicsCustomChart

Use this page's pattern when you want a reusable chart API that owns a layout recipe and still supports push updates.

Custom layout HOCs

Use XYCustomChart, OrdinalCustomChart, NetworkCustomChart, or GeoCustomChart for static scene geometry without simulation.

Layout contract

The layout receives scales, dimensions, resolved theme colors, the custom config, and a scratch PhysicsPipelineStore. It returns declarative physics pieces. The same conversion can be reused by spawnDatum, so pushed rows enter the live chart without rebuilding the page.

JSX

import { PhysicsCustomChart, arrivalReplay, collidersFromScales } from "semiotic/physics" function routingLayout(ctx) { const replay = arrivalReplay( ctx.data.map((packet, index) => packetToSpawn(packet, index, ctx)) ) return { initialSpawns: replay.initialSpawns, initialSpawnPacing: replay.initialSpawnPacing, colliders: [ ...collidersFromScales({ plot: ctx.dimensions.plot, xBands }), ...barriers ], sensors: [ { id: "sensor-review", shape: { type: "aabb", x, y, width, height } } ], config: { observation: { sensors: { "sensor-review": { binId: "Review lane", enterType: "physics-proximity-enter", exitType: "physics-proximity-exit" } } } }, backgroundOverlays: <svg>{/* labels, guides, sensor zones */}</svg>, semanticItems: [ { id: "review-lane", label: "Review lane", x, y, shape: "rect", width, height } ] } } <PhysicsCustomChart ref={chartRef} data={packets} layout={routingLayout} layoutConfig={{ bias, launchSpeed }} spawnDatum={packetToSpawn} onObservation={recordSensorEvent} />

Recipe helpers

The M6 recipe kit keeps common physics layout chores out of chart code: scale-derived colliders, Galton pegs, token-to-body spawns, sediment baking, and arrival-paced replay.

JSX

import { galtonPegs, sedimentBake, spawnFromTokens } from "semiotic/physics" import { generateTokens, layoutTokenGrid } from "semiotic/recipes" const tokenSet = generateTokens(samples, { tokenType: "dot", tokenSemantics: "posterior-sample", countStrategy: "posterior-sample", tokenCount: 80 }) const spawns = spawnFromTokens(layoutTokenGrid(tokenSet, grid), { idPrefix: "posterior", radius: 4, jitter: { x: 6, y: 2 }, seed: 12 }) const pegs = galtonPegs({ plot: ctx.dimensions.plot, rows: 8 }) const baked = sedimentBake(ctx.world.readSediment(), { baselineY })

When to use it

Use it when sensors and barriers are part of the chart semantics, not just decoration.
Use it when a reusable chart should expose data-oriented props instead of raw body specs.
Use it when the chart needs realtime push, pushMany, remove, or clear behavior.
Use the non-physics custom HOCs when the layout is static SVG or canvas geometry.

Props

Prop	Type	Required	Default	Description
`data`	array	—	`[]`	Initial rows to convert into physics bodies.
`layout`	function	Yes	—	Receives the physics custom layout context and returns bodies, colliders, sensors, semantic items, overlays, and config.
`layoutConfig`	object	—	`{}`	Custom options passed through to the layout function.
`config`	object	—	—	Base PhysicsPipelineConfig merged with the layout result.
`spawnDatum`	function	—	—	Converts pushed rows into one or more PhysicsQueuedSpawn objects.
`colorBy`	string \| function	—	—	Categorical field used by the default body style.
`colorScheme`	array \| object \| string	—	—	Palette or keyed color map for resolveColor.
`xExtent`	array	—	`[0, 1]`	Domain for the x scale exposed to the layout context.
`yExtent`	array	—	`[0, 1]`	Domain for the y scale exposed to the layout context.
`size`	array	—	`[700, 380]`	[width, height] in pixels.
`paused`	boolean	—	`false`	Pause the simulation.
`accessibleTable`	boolean	—	`true`	Expose layout semanticItems through the skip link and data-summary table.
`description`	string	—	—	Accessible label for the physics chart frame.
`summary`	string	—	—	Screen-reader-only summary text for the chart.
`hoverRadius`	number	—	`16`	Pixel hit radius for body hover tooltips.
`tooltip`	boolean \| function \| object	—	`true`	Enable the default body tooltip, pass a custom tooltip renderer/config, or set false to disable hover tooltips.
`frameProps`	object	—	—	Advanced StreamPhysicsFrame props.