Custom Charts — Overview — 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/custom-charts/overview

Custom Charts

When the chart catalog doesn’t fit, Semiotic gives you an escape hatch: four HOCs that hand a layout function a typed context and let it emit scene primitives directly. The Stream Frame still owns the hard parts — scales, theme, canvas hit-testing, keyboard navigation, transitions, decay, SSR/PNG export — so your layout only has to compute geometry. A bespoke graphic lands as a reusable recipe, not a one-off D3 script, and inherits the whole engineering substrate for free.

The frame gives custom geometry Semiotic’s runtime affordances. The recipe gives that geometry meaning. SeeCustom Charts as Reception Strategies.

JSX

import { NetworkCustomChart } from "semiotic/network" import { packedClusterMatrix } from "semiotic/recipes" <NetworkCustomChart nodes={data} layout={packedClusterMatrix} layoutConfig={{ /* ... */ }} />

Intent Mark · part-to-whole

XYCustomChart: part-to-whole for general-technical. A unit grid makes composition concrete through repeated, inspectable units.

{ "ididVersion": "0.1", "chartId": "custom-charts-overview-waffle", "title": "Waffle chart", "intent": { "primary": "part-to-whole", "secondary": [ "compare-categories", "explanation" ] }, "audience": { "primary": "general-technical", "familiarityAssumptions": { "waffleChart": "medium", "partToWhole": "high" }, "literacyTargets": [ { "feature": "unit-based composition", "rationale": "Readers can reason about proportions through repeated visible units." } ] }, "reception": { "channels": [ "visual", "interactive", "screen-reader", "agent" ], "strengths": [ "memorable", "glanceable", "explainable", "teaching-friendly" ], "risks": [ "precise comparison may be harder than a bar chart", "individual cells can become navigation noise" ], "scaffolds": [ "legend", "category summary", "accessible table", "description" ], "memorableForm": true }, "designContract": { "chartFamily": "XYCustomChart", "whyThisForm": "A unit grid makes composition concrete through repeated, inspectable units.", "whyNotDefault": "A pie chart would show share but provide less unit-level evidence and less interaction surface.", "risks": [ "precise comparison may be harder than a bar chart", "individual cells can become navigation noise" ], "misuse": [ "too many categories", "too many units", "false precision", "treating each cell as a separate semantic datum" ] }, "accessibility": { "navigation": true, "dataFallback": true, "manualChecks": [ "real screen-reader behavior", "keyboard order quality", "custom metaphor comprehension", "animation distraction" ] }, "provenance": { "reviewStatus": "docs example", "generatedBy": "Semiotic recipe intelligence" } }

The four escape-hatch HOCs

Each wraps a Stream Frame and differs only in the context it hands the layout (which scales and data shape) and the scene primitives it can paint:

HOC	Import	Layout context	Emits	Recipes
`XYCustomChart`	`semiotic/xy`	data, scales {x,y}, dimensions, theme, resolveColor, config	point / line / area / rect / symbol scene nodes + overlays	waffle, calendar, streamgraph
`OrdinalCustomChart`	`semiotic/ordinal`	data, scales {o,r,projection}, dimensions, theme, resolveColor, config	rect / wedge / connector / trapezoid / symbol nodes + overlays	marimekko, bullet, parallel coordinates
`NetworkCustomChart`	`semiotic/network`	nodes, edges, dimensions, theme, resolveColor, config, selection	circle / rect / arc / symbol nodes, edges, labels + overlays	flextree, dagre, lineage DAG, packed-cluster matrix
`GeoCustomChart`	`semiotic/geo`	areas, points, lines, GeoScales, dimensions, theme, resolveColor, config	geographic area / point / line scene nodes + overlays	isometric landmark atlas, hex territory board

Building blocks

Custom Layouts

The four escape-hatch HOCs, the layout-function contract, the scene primitives, and the full recipe gallery (waffle, calendar, flextree, dagre, marimekko, bullet, parallel coordinates, isometric landmarks).

PhysicsCustomChart

The physics escape hatch: a layout function returns bodies, barriers, proximity sensors, overlays, and observation metadata while the chart still exposes data-oriented props and realtime push methods.

Glyph Marks

The per-datum shape channel: the symbol scene-node, d3-shape glyphs, and the composite-glyph model (a filled base mark + an optional stroked inner icon).

Recipe Chrome Kit

Small composable helpers for the decoration recipes draw in their overlays — group enclosures, band/axis labels, leader-line callouts, the node.data reader, and color/shade utilities.

Worked examples

Full recipes built on the escape hatch — each is interactive:

Satellites in Space

The packedClusterMatrix recipe — a matrix of packed beeswarm clusters with four-channel composite glyphs, banded rows, and callouts. Fully interactive controls.

Kafka Streams topology

The lineageDagLayout recipe — a layered DAG of composite node glyphs with reach-dimming and linked selection.

GoFish layouts

GoFish's baked DisplayList render IR mapped onto a custom layout by role — GoFish owns the geometry, Semiotic owns interaction and accessibility.

Marimekko

Variable-width stacked bars via the marimekko ordinal recipe.

When to reach for it

Prefer a built-in HOC whenever one fits — they’re simpler and fully supported. Reach for a custom layout when the geometry itself is the point (a packed matrix, a bespoke DAG, a multi-channel glyph) and no built-in expresses it. The recipe still gets interaction, accessibility, theming, and server rendering from the frame; you only write the layout.