}
/>
```
Key props: **`nodes`** and **`edges`** (both required), `nodeIDAccessor` (default "id"), `sourceAccessor` (default "source"), `targetAccessor` (default "target"), `colorBy`, `nodeSize` (number, string field name, or function), `nodeSizeRange`, `showLabels`, `showLegend`, `tooltip`
**Note**: Always use `ForceDirectedGraph` (not `StreamNetworkFrame`) unless you need sophisticated control it doesn't expose. `StreamNetworkFrame` is a low-level escape hatch whose callbacks receive internal `RealtimeNode` wrappers — access your data via `.data` (e.g., `nodeStyle={(d) => ({ fill: d.data?.color })}`). HOC components like `ForceDirectedGraph` handle this automatically.
### ForceDirectedGraph with custom click/hover
```jsx
import { useState } from "react"
import { ForceDirectedGraph } from "semiotic/ai"
const [selected, setSelected] = useState(null)
{
// d is { type: "node"|"edge", data: , x, y } or null
if (d?.type === "node") setSelected(d.data)
},
customHoverBehavior: (d) => {
// same shape as click — d.data is your original object
if (d?.type === "node") console.log("Hovering:", d.data.id)
},
background: "#1a1a2e",
}}
/>
```
Key props: `frameProps` passes through to the underlying `StreamNetworkFrame` for advanced control (custom click/hover, background, annotations). Callback `d.data` is always your original node/edge object.
### SankeyDiagram
```jsx
import { SankeyDiagram } from "semiotic/ai"
const edges = [
{ source: "Salary", target: "Budget", value: 5000 },
{ source: "Freelance", target: "Budget", value: 2000 },
{ source: "Budget", target: "Rent", value: 2500 },
{ source: "Budget", target: "Food", value: 1200 },
{ source: "Budget", target: "Transport", value: 800 },
{ source: "Budget", target: "Savings", value: 2500 }
]
```
Key props: **`edges`** (required, nodes inferred), `valueAccessor` controls band width
### ProcessSankey
```jsx
import { ProcessSankey } from "semiotic/ai"
const nodes = [
{ id: "Alice", category: "Person", xExtent: ["2026-01-06", "2026-01-06"] },
{ id: "Bob", category: "Person", xExtent: ["2026-02-01", "2026-02-01"] },
{ id: "Eng", category: "Team" },
{ id: "Release", category: "Milestone", xExtent: ["2026-04-15", "2026-05-30"] },
]
const edges = [
{ id: "alice-eng", source: "Alice", target: "Eng", value: 8,
startTime: "2026-01-20", endTime: "2026-02-10" },
{ id: "bob-eng", source: "Bob", target: "Eng", value: 5,
startTime: "2026-02-15", endTime: "2026-03-15" },
{ id: "eng-rel", source: "Eng", target: "Release", value: 13,
startTime: "2026-04-15", endTime: "2026-05-15" },
]
```
Key props: **`edges`** with `startTime`/`endTime`, **`domain`** (required `[t0, t1]`); nodes optionally carry `xExtent: [start, end]` to bound the lane (`min(xExtent[0], earliestEdge)` to `max(xExtent[1], latestEdge)`). Use when flow events have timestamps; use SankeyDiagram for static total-flow snapshots.
### ChordDiagram
```jsx
import { ChordDiagram } from "semiotic/ai"
const edges = [
{ source: "US", target: "EU", value: 500 },
{ source: "US", target: "Asia", value: 300 },
{ source: "EU", target: "US", value: 400 },
{ source: "EU", target: "Asia", value: 200 },
{ source: "Asia", target: "US", value: 350 },
{ source: "Asia", target: "EU", value: 250 }
]
```
Key props: **`edges`** (required), shows bidirectional relationships in a circle
---
## Realtime — Push API via Ref
### RealtimeLineChart
```jsx
import { useRef, useEffect } from "react"
import { RealtimeLineChart } from "semiotic/ai"
const chartRef = useRef()
// Push data — MUST include a time field
useEffect(() => {
const interval = setInterval(() => {
chartRef.current?.push({ time: Date.now(), value: Math.random() * 100 })
}, 500)
return () => clearInterval(interval)
}, [])
```
Key props: `timeAccessor`, `valueAccessor`, `windowSize`, `stroke`, `strokeWidth`
### RealtimeHistogram
```jsx
import { useRef, useEffect } from "react"
import { RealtimeHistogram } from "semiotic/ai"
const chartRef = useRef()
// IMPORTANT: Include time field even though this shows a distribution — it's used for windowing
useEffect(() => {
const interval = setInterval(() => {
chartRef.current?.push({
time: Date.now(),
value: Math.random() * 1000
})
}, 200)
return () => clearInterval(interval)
}, [])
```
Key props: **`binSize`** (required), `timeAccessor` ("time"), `valueAccessor` ("value"). Without a time field in your data, the chart renders blank.
### RealtimeHeatmap
```jsx
import { useRef, useEffect } from "react"
import { RealtimeHeatmap } from "semiotic/ai"
const chartRef = useRef()
// IMPORTANT: Data must have fields matching timeAccessor and valueAccessor (defaults: "time" and "value")
useEffect(() => {
const interval = setInterval(() => {
chartRef.current?.push({
time: Date.now(),
value: Math.random() * 500
})
}, 100)
return () => clearInterval(interval)
}, [])
```
Key props: `timeAccessor` ("time"), `valueAccessor` ("value"), `heatmapXBins`, `heatmapYBins`. Both accessors must match your data fields or the chart renders blank.
### Streaming Sankey with Particles (StreamNetworkFrame)
Use `StreamNetworkFrame` only when you need low-level control that HOC charts don't expose. For most cases, use `ForceDirectedGraph`, `SankeyDiagram`, or `ChordDiagram` instead.
```jsx
import { useRef, useEffect } from "react"
import { StreamNetworkFrame } from "semiotic"
const chartRef = useRef()
useEffect(() => {
// Push individual edges — NOT a full snapshot.
// Each push adds one edge event to the streaming sankey.
chartRef.current.push({ source: "Salary", target: "Budget", value: 5000 })
chartRef.current.push({ source: "Freelance", target: "Budget", value: 1500 })
// Or batch multiple edges at once:
chartRef.current.pushMany([
{ source: "Budget", target: "Rent", value: 2000 },
{ source: "Budget", target: "Food", value: 800 },
{ source: "Budget", target: "Savings", value: 1500 },
])
}, [])
```
Key props: `chartType="sankey"`, `showParticles` (boolean — enables animated particles flowing along edges), `particleStyle` (`{ radius, opacity, speedMultiplier, maxPerEdge, colorBy }`), push via ref (`push` for single edge, `pushMany` for batch, `clear` to reset)
### Streaming any chart type via Stream Frames
The Realtime* HOCs are convenience wrappers. For streaming versions of scatter, stacked area, bar, or any other chart, use the corresponding Stream Frame with `runtimeMode="streaming"`:
```jsx
import { useRef } from "react"
import { StreamXYFrame } from "semiotic/xy"
const chartRef = useRef()
// Push data via ref — same push API as Realtime* HOCs
chartRef.current?.push({ time: Date.now(), size: 42, category: "A" })
```
Available Stream Frames: `StreamXYFrame` (line, area, stackedArea, scatter), `StreamOrdinalFrame` (bar, grouped bar), `StreamNetworkFrame` (sankey, force, chord)
---
## Server-Side Rendering
### renderToStaticSVG (Node.js)
```ts
// IMPORTANT: frameType is "xy" | "ordinal" | "network" — NOT a component name like "BarChart"
import { renderOrdinalToStaticSVG } from "semiotic/server"
const data = [
{ category: "Q1", value: 120 },
{ category: "Q2", value: 148 },
{ category: "Q3", value: 135 },
{ category: "Q4", value: 162 },
]
const svg: string = renderOrdinalToStaticSVG({
data,
categoryAccessor: "category",
valueAccessor: "value",
width: 600,
height: 400,
})
// Or use the generic function:
import { renderToStaticSVG } from "semiotic/server"
const svg2 = renderToStaticSVG("ordinal", { data, categoryAccessor: "category", valueAccessor: "value" })
```
Key: `renderToStaticSVG(frameType, props)` where frameType is `"xy"` | `"ordinal"` | `"network"`. Type-specific shortcuts: `renderXYToStaticSVG`, `renderOrdinalToStaticSVG`, `renderNetworkToStaticSVG`.
---
## Export
### exportChart (browser)
```jsx
import { useRef } from "react"
import { Scatterplot } from "semiotic/ai"
import { exportChart } from "semiotic"
const containerRef = useRef(null)
// Pass the WRAPPER DIV, not the SVG element — exportChart finds canvas+SVG internally
```
Key: `exportChart(wrapperDiv, { format, filename, scale, background })`. It queries the wrapper for canvas and SVG elements internally. Default format: PNG with 2x scale.
---
## Theming & Brand Styling
### CSS Custom Properties (no React context needed)
```jsx
// Dark theme via CSS custom properties on a wrapper div
```
### ThemeProvider (React context)
```jsx
import { ThemeProvider, DARK_THEME, COLOR_BLIND_SAFE_CATEGORICAL } from "semiotic"
// Preset dark theme
// Custom brand theme (partial merge with defaults)
// Color-blind safe palette (Wong 2011 — 8 colors)
```
### Annotations with Theme Colors
```jsx
// Annotations inherit --semiotic-primary and --semiotic-text-secondary from theme
Record month
)},
// Enclose a cluster of outliers
{ type: "enclose", coordinates: outlierPoints, label: "Outlier cluster", padding: 15 },
]}
showGrid
/>
```
---
## Click Handlers
### onClick on BarChart
```jsx
import { BarChart } from "semiotic/ai"
{
console.log(`Clicked ${datum.region}: $${datum.revenue}`)
setSelectedRegion(datum.region)
}}
/>
```
Key props: `onClick` receives the original datum and pixel coordinates. Works on all chart types.
---
## Linked Crosshair (Multi-chart Hover Sync)
### Synced crosshair across time-series charts
```jsx
import { LineChart, LinkedCharts } from "semiotic/ai"
```
Key props: `linkedHover` with `mode: "x-position"` broadcasts the hovered X value. Each chart shows its own tooltip with its own Y values. Use for multi-metric dashboards.
---
## Category Format (Custom Tick Labels)
### Truncated category labels
```jsx
import { BarChart } from "semiotic/ai"
label.length > 12 ? label.slice(0, 12) + "…" : label}
/>
```
Key props: `categoryFormat` receives each tick label and returns a formatted string. Available on all ordinal HOCs except Pie/Donut.
---
## Ordinal Annotations
### Threshold + category highlight on BarChart
```jsx
import { BarChart } from "semiotic/ai"
```
Key props: `y-threshold` works on vertical ordinal charts. `category-highlight` highlights a category column. `labelPosition` controls label placement.