[](https://mcptoplist.com/server/io.github.nteract%2Fsemiotic)
[](https://semiotic.nteract.io)
[](https://github.com/nteract/semiotic/actions/workflows/node.js.yml)
[](https://www.npmjs.com/package/semiotic)
[](https://www.typescriptlang.org/)
[](https://mseep.ai/app/nteract-semiotic)
[](https://mcpqueen.com/s/io.github.nteract/semiotic)
A React data visualization library designed for AI-assisted development and streaming data.
## Install
```bash
npm install semiotic
```
Requires React 18.1+ or React 19.
## First Chart
```jsx
import { LineChart } from "semiotic/xy"
const signups = [
{ week: 1, signups: 120 },
{ week: 2, signups: 180 },
{ week: 3, signups: 150 },
{ week: 4, signups: 240 },
{ week: 5, signups: 310 },
]
export default function SignupsChart() {
return (
)
}
```
`xAccessor` and `yAccessor` name the fields to plot, and `title` gives the
chart its accessible name. `LineChart` needs numeric x values (numbers or
timestamps); for named categories such as month names, use `BarChart` with
`categoryAccessor`. More complete examples follow under
[Quick Examples](#quick-examples).
Start with a small chart component. Add network graphs, streaming data and
coordinated views when the task needs them. Structured schemas, diagnostics
and rendering evidence help coding assistants implement, check and repair
chart configurations.
Work through a complete task: [check category totals](https://semiotic.nteract.io/tasks/compare-category-totals),
[maintain a live chart](https://semiotic.nteract.io/tasks/update-live-chart), or
[correct a published chart](https://semiotic.nteract.io/tasks/correct-published-chart).
The [source task packets](ai/task-packets/index.json) identify their build and
evidence scope; source availability does not establish installed or deployed parity.
## Quick Examples
Each example is a complete component. Examples that use one chart family
import from that family's entry; the coordination examples import from
`semiotic`, which exports `LinkedCharts` and `ChartContainer` alongside the
charts.
### Standard Charts
Line, bar, scatter, and area charts share the same accessor-driven API:
```jsx
import { LineChart } from "semiotic/xy"
import { BarChart } from "semiotic/ordinal"
const revenue = [
{ month: 1, revenue: 4200 },
{ month: 2, revenue: 5100 },
{ month: 3, revenue: 6800 },
{ month: 4, revenue: 5900 },
]
const departments = [
{ department: "Design", region: "East", sales: 12 },
{ department: "Sales", region: "West", sales: 30 },
{ department: "Support", region: "East", sales: 18 },
]
export function StandardCharts() {
return (
<>
>
)
}
```
### Coordinated Dashboard
Hover one chart and highlight the same data in another through a shared selection:
```jsx
import { LinkedCharts, Scatterplot, BarChart } from "semiotic"
const people = [
{ age: 31, income: 52, region: "East" },
{ age: 44, income: 78, region: "West" },
{ age: 38, income: 61, region: "East" },
{ age: 52, income: 90, region: "West" },
]
const totals = [
{ region: "East", total: 113 },
{ region: "West", total: 168 },
]
export function RegionDashboard() {
return (
)
}
```
### Streaming Metrics with Decay
Live data fades old points, flashes new ones, flags stale feeds. Omit `data`
and push through a ref from an effect, an event handler, or a socket callback:
```jsx
import { useEffect, useRef } from "react"
import { RealtimeLineChart } from "semiotic/realtime"
export function CpuMonitor() {
const chartRef = useRef(null)
useEffect(() => {
// Replace the timer with your metrics source.
const timer = setInterval(() => {
chartRef.current?.push({ time: Date.now(), value: 40 + Math.random() * 20 })
}, 250)
return () => clearInterval(timer)
}, [])
return (
)
}
```
### Network Graphs
Force-directed graphs and Sankey diagrams — same API as LineChart:
```jsx
import { ForceDirectedGraph, SankeyDiagram } from "semiotic/network"
const people = [
{ id: "Ada", team: "Platform" },
{ id: "Lin", team: "Design" },
{ id: "Sam", team: "Platform" },
]
const friendships = [
{ source: "Ada", target: "Lin" },
{ source: "Lin", target: "Sam" },
]
const budgetFlows = [
{ from: "Budget", to: "Design", amount: 40 },
{ from: "Budget", to: "Engineering", amount: 60 },
{ from: "Engineering", to: "Platform", amount: 35 },
]
export function Networks() {
return (
<>
>
)
}
```
### Geographic Visualization
Choropleth maps, flow maps, and distance cartograms with canvas rendering,
zoom/pan, tile basemaps, and animated particles. This example joins your rows
to the bundled `world-110m` geography, which needs the optional `world-atlas`
peer dependency (`npm install world-atlas`):
```jsx
import { useEffect, useState } from "react"
import { ChoroplethMap, mergeData, resolveReferenceGeography } from "semiotic/geo"
const gdpByCountry = [
{ country: "United States of America", gdp: 27.4 },
{ country: "China", gdp: 17.8 },
{ country: "Germany", gdp: 4.5 },
]
export function WorldGdpMap() {
const [areas, setAreas] = useState([])
useEffect(() => {
let cancelled = false
resolveReferenceGeography("world-110m").then((world) => {
if (cancelled) return
setAreas(
mergeData(world, gdpByCountry, { featureKey: "properties.name", dataKey: "country" })
)
})
return () => {
cancelled = true
}
}, [])
return (
feature.properties.gdp}
colorScheme="viridis" projection="equalEarth" zoomable tooltip
title="GDP by country"
/>
)
}
```
`FlowMap` and `DistanceCartogram` follow the same accessor pattern. In this
sketch `airports`, `routes`, and `cities` stand for your own arrays:
```jsx
import { FlowMap, DistanceCartogram } from "semiotic/geo"
```
### Streaming System Monitor
Live service topology with threshold alerting and click-to-inspect:
```jsx
import { useEffect, useRef } from "react"
import { StreamNetworkFrame, ChartContainer, DetailsPanel, LinkedCharts } from "semiotic"
export function SystemMonitor() {
const chartRef = useRef(null)
useEffect(() => {
// Replace the timer with your request stream.
const timer = setInterval(() => {
chartRef.current?.push({ source: "API", target: "Orders", value: 15 })
}, 500)
return () => clearInterval(timer)
}, [])
return (
{(datum) =>
{datum.id}: {datum.value} req/s
}
}>
n.value, warning: 100, critical: 250 }}
/>
)
}
```
## All Chart Components
| Category | Components |
|---|---|
| **XY** | `LineChart` `AreaChart` `DifferenceChart` `StackedAreaChart` `BumpChart` `Scatterplot` `ConnectedScatterplot` `BubbleChart` `Heatmap` `QuadrantChart` `MultiAxisLineChart` `MinimapChart` `CandlestickChart` `WaterfallChart` `ScatterplotMatrix` |
| **Categorical** | `BarChart` `StackedBarChart` `GroupedBarChart` `LikertChart` `SwimlaneChart` `FunnelChart` `SwarmPlot` `BoxPlot` `Histogram` `ViolinPlot` `RidgelinePlot` `DotPlot` `PieChart` `DonutChart` `GaugeChart` `RadarChart` |
| **Network** | `ForceDirectedGraph` `ChordDiagram` `SankeyDiagram` `ProcessSankey` `TreeDiagram` `Treemap` `CirclePack` `OrbitDiagram` |
| **Geo** (`semiotic/geo`) | `ChoroplethMap` `ProportionalSymbolMap` `FlowMap` `DistanceCartogram` |
| **Realtime** | `RealtimeLineChart` `RealtimeHistogram` `TemporalHistogram` `RealtimeSwarmChart` `RealtimeWaterfallChart` `RealtimeHeatmap` |
| **Physics** (`semiotic/physics`) | `GaltonBoardChart` `EventDropChart` `UnitPileChart` `CollisionSwarmChart` `GauntletChart` `CrucibleChart` `ProcessFlowChart` `PacketFlowChart` `ChainReactionChart` |
| **Value and text** | `BigNumber` (`semiotic/value`) `WordCloud` (`semiotic/wordcloud`) |
| **Custom layouts** | `XYCustomChart` `OrdinalCustomChart` `NetworkCustomChart` `GeoCustomChart` (`semiotic/geo`) `PhysicsCustomChart` (`semiotic/physics`) |
| **Coordination** | `LinkedCharts` |
| **Layout** | `ChartGrid` `ContextLayout` `CategoryColorProvider` |
| **Frames** | `StreamXYFrame` `StreamOrdinalFrame` `StreamNetworkFrame` `StreamGeoFrame` (`semiotic/geo`) `StreamPhysicsFrame` (`semiotic/physics`) |
### Vega-Lite Translation
Paste a Vega-Lite spec, get a Semiotic chart:
```jsx
import { fromVegaLite } from "semiotic/data"
import { configToJSX, fromConfig } from "semiotic"
const config = fromVegaLite({
mark: "bar",
data: { values: [{ a: "A", b: 28 }, { a: "B", b: 55 }] },
encoding: {
x: { field: "a", type: "nominal" },
y: { field: "b", type: "quantitative" },
},
})
// Render directly
const { componentName, props } = fromConfig(config)
// → componentName: "BarChart", props: { data, categoryAccessor: "a", valueAccessor: "b" }
// Or generate JSX code
configToJSX(config)
// →
```
Supports bar, line, area, point, rect, arc, tick marks with encoding translation
for color, size, aggregation, and binning.
### Conversation Arc Telemetry
Capture and replay the path an AI-assisted chart session took:
```ts
import {
createLocalStorageConversationArcSink,
enableConversationArc,
getConversationArcStore,
loadConversationArc,
registerConversationArcSink,
} from "semiotic/ai"
const sink = createLocalStorageConversationArcSink({ key: "my-app:arc" })
registerConversationArcSink(sink)
enableConversationArc({ sessionId: "session-abc" })
getConversationArcStore().record({ type: "chart-rendered", component: "LineChart" })
loadConversationArc(sink.load(), { enabled: false })
```
## What's New in 3.13.3
3.13.3 improves streaming chart suggestions with field cardinality, additivity,
and schema warnings, and adds count aggregation for realtime histograms.
Streaming charts preserve extents, hover detail, and keyboard focus as data
changes. Pie, donut, and network charts use more of their available space,
with matching server rendering. This release also improves chart error
recovery, legend fitting, heatmap colors, and compositional routing.
See [the changelog](CHANGELOG.md#3133---2026-10-29) for the complete fixes and additions.
## Why Semiotic
Semiotic is a data visualization library for React that combines broad chart
coverage with AI tooling. It supports network graphs, streaming data,
statistical distributions and coordinated views, with schemas, examples and
diagnostics for implementing and checking each task. Check the project's
existing dependencies first: extending its current charting library may be
the best fit for a small change.
### Built for AI-assisted development
Semiotic provides a workflow for generating, checking and repairing chart
configurations. The [July 27, 2026 evaluation](evals/reports/openai-gpt-5.6-2026-07-27/README.md)
reports model- and task-specific results; it does not guarantee first-try correctness.
- **`semiotic/ai`** — a single import with the schema-backed chart capability catalog (XY, ordinal, network, realtime, geo, value, and portable recipes), optimized for LLM code generation. See `ai/surface-manifest.json` for the generated current inventory. Named imports now tree-shake across published chunks. Prefer family subpaths (`semiotic/xy`, `semiotic/geo`, `semiotic/value`, …) in production code to keep the intended chart family explicit; the cold-consumer table below reports initial-load and on-demand costs.
- **`ai/schema.json`** — machine-readable prop schemas for every component
- **`npx -y -p semiotic semiotic-mcp`** — an MCP server for tool-based chart rendering in any MCP client
- **`npx -p semiotic semiotic-ai --doctor`** — validate component + props JSON from the command line with typo suggestions and anti-pattern detection
- **`diagnoseConfig(component, props)`** — programmatic anti-pattern detector with actionable fixes, spanning validation, encoding, accessibility, and misleading-design (deception) checks
- **`auditData(component, props, data?)`** — chart-aware numeric preflight for inputs that pass schema validation but break the math: non-finite values, zero-span domains, invalid log inputs, negative size geometry, unsafe normalized totals, and scale-dominating outliers. Returns bounded row evidence and flows into `diagnoseConfig`, Chart Clinic, CLI doctor, and opt-in `ChartContainer` notifications
- **`AGENTS.md`** — concise repository workflow shared by modern coding agents;
`CLAUDE.md` imports it and Copilot receives a short compatibility bridge
- **`ai/reference.md`** — complete on-demand product reference, kept out of
always-loaded coding-agent context
- **`llms.txt`** — machine-readable documentation following the emerging standard
Every chart includes a built-in error boundary, dev-mode validation
warnings with typo suggestions, and accessibility features (canvas
`aria-label`, keyboard-navigable legends, keyboard live-region announcements, SVG
``/``) so AI-generated code fails gracefully with
actionable diagnostics instead of a blank screen.
### Accessibility is a release surface
The [European Accessibility Act](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=legissum%3A4403933)
has applied to covered products and services since 28 June 2025. A chart
library cannot certify an application's legal compliance: scope, content,
surrounding controls, testing, and national enforcement remain the
application owner's responsibility. Semiotic supplies testable infrastructure
for that work: keyboard interaction, accessible data tables, layered
descriptions, structured navigation, reduced-motion and forced-colors paths,
and WCAG-derived contrast tests for shipped theme presets. See the
[Accessibility docs](https://semiotic.nteract.io/accessibility/overview) and
run the application's own assistive-technology and user testing.
### Beyond standard charts
**Network visualization.** Force-directed graphs, Sankey diagrams, chord
diagrams, tree layouts, treemaps, circle packing, and orbit diagrams — all
as React components with the same prop API as LineChart.
**Streaming data.** Realtime charts render on canvas at 60fps with a
ref-based push API. Rapid network edge pushes coalesce into one layout per
animation frame, while read/mutation methods preserve synchronous read-after-write
semantics. Built-in decay, pulse, and staleness encoding for monitoring dashboards.
**Coordinated views.** `LinkedCharts` provides hover cross-highlighting,
brush cross-filtering, coordinate-based linked crosshairs, and selection
synchronization across any combination of chart types through shared selection state.
**Geographic visualization.** Choropleth maps, proportional symbol maps, flow
maps with animated particles, and distance cartograms — all canvas-rendered
with d3-geo projections, zoom/pan, tile basemaps, and drag-rotate globe spinning.
**Statistical summaries.** Box plots, violin plots, swarm plots, histograms,
LOESS smoothing, forecast with confidence envelopes, and anomaly detection.
Marginal distribution graphics on scatterplot axes with a single prop.
**First-class annotations.** Annotations are data-bound objects, not post-hoc
artwork. Labels, callouts, thresholds, enclosures, statistical overlays, and
React widgets move with the chart and render through browser, SSR, and export
paths. Opt into placement, hierarchy, density, progressive disclosure,
audience-aware amount, provenance, and editorial lifecycle when the chart
needs to communicate more than its encoding alone.
### Choose the API layer
| Layer | For | Example |
|---|---|---|
| **Charts** | Common chart forms with chart-level props | `` |
| **Frames** | Full control over rendering, interaction, and layout | `` |
Chart HOCs register only the mark plugins they need. Direct `StreamXYFrame`
loads the remaining built-ins on first client paint. Call
`registerBuiltInXYPlugins()` from `semiotic/xy` or `semiotic/realtime/core`
before the first render when SSR or the first frame must include marks.
Every Chart component accepts a `frameProps` prop to access the underlying
Frame API without leaving the simpler interface.
### Serialization and interop
Charts serialize to JSON and back: `toConfig`, `fromConfig`, `toURL`,
`copyConfig`, `configToJSX`. Have Vega-Lite specs? `fromVegaLite(spec)`
translates them to Semiotic configs — works with `configToJSX()` for
full round-trip from notebooks and AI-generated specs.
Need an external pitfall review? The experimental `unstable_toDataPitfallsChain()` builds a
dependency-free chain input for [`datapitfalls`](https://github.com/bjonesdataliteracy/datapitfalls),
combining the Semiotic config, JSX, reader grounding, diagnostics,
accessibility audit, and optional rendered SVG/image evidence:
```ts
import { unstable_toDataPitfallsChain } from "semiotic/experimental"
import { detectPitfalls } from "datapitfalls"
const input = unstable_toDataPitfallsChain("LineChart", props, {
narrative: "Monthly sales are accelerating.",
rendered: { svg, evidence },
})
const report = await detectPitfalls(input, { apiKey: process.env.ANTHROPIC_API_KEY })
```
The return path stays dependency-free too. Use whole-chart findings as
`ChartContainer` notifications, and only turn findings into annotations after
your app can anchor them to marks or semantic positions:
```tsx
import { ChartContainer } from "semiotic"
import { LineChart } from "semiotic/xy"
import {
unstable_toDataPitfallsAnnotations,
unstable_toDataPitfallsNotifications,
} from "semiotic/experimental"
const notifications = unstable_toDataPitfallsNotifications(report)
const annotations = unstable_toDataPitfallsAnnotations(report, {
anchorFor: (finding) =>
finding.ruleId === "truncated-axis" ? { x: 9, y: 9000 } : null,
})
```
### When to use something else
Need a standard bar or line chart for a dashboard you'll never need to
customize beyond colors and labels? [Recharts](https://recharts.org) has a
larger ecosystem and more community examples. Need GPU-accelerated rendering
for millions of data points? [Apache ECharts](https://echarts.apache.org)
handles that scale.
Semiotic is for projects that outgrow those libraries — when you need
network graphs alongside time series, streaming data alongside static
snapshots, or coordinated views across chart types.
## Bundle Sizes
Semiotic ships 42 stable JavaScript entry points (41 subpaths plus the root). **Don't import from `"semiotic"` unless you need everything** — use the smallest sub-path that matches your charts or tooling.
Custom network layouts can opt into a virtual zoom/pan viewport through `semiotic/network/zoom`. It exports `ZoomableNetworkCustomChart` and projected-size/LOD hooks; ordinary chart imports exclude its gesture and LOD runtime.
The numbers below are **first-party artifact cost**: the gzip size of Semiotic's own code for each sub-path. They exclude React and other runtime dependencies, and each row counts every chunk the entry can reach, including code loaded only on demand, so they are not a prediction of a cold application bundle. Do not add artifact rows to estimate an app: dependency resolution and cross-import deduplication happen in the consumer bundler and are measured separately below.
| Entry Point | gzip | What's inside |
|---|---|---|
| `semiotic/atlas` | **330 KB** | Motif Braid, Dependency Forest, and Flow Circuit readers |
| `semiotic/atlas/core` | **15 KB** | Network Atlas preparation, projections, and evidence queries |
| `semiotic/access` | **32 KB** | Chart Access Contract factory and first-wave baseline contracts |
| `semiotic/evidence` | **49 KB** | Chart Evidence Envelope, deterministic hashing, and publication gate |
| `semiotic/artifact` | **128 KB** | Renderer-independent contracts, claims, time, policy, grounding, and transfer audits |
| `semiotic/artifact/react` | **4 KB** | Accessible progressive disclosure for artifact contracts and policy evaluations |
| `semiotic/line` | **156 KB** | LineChart only — one-chart micro boundary |
| `semiotic/xy` | **195 KB** | LineChart, AreaChart, Scatterplot, Heatmap, + 8 more XY charts |
| `semiotic/ordinal` | **142 KB** | BarChart, PieChart, BoxPlot, Histogram, + 11 more categorical charts |
| `semiotic/network` | **188 KB** | ForceDirectedGraph, SankeyDiagram, ProcessSankey, Treemap, + 4 more |
| `semiotic/network/zoom` | **198 KB** | Optional virtual network viewport, camera controls and consumer-owned LOD |
| `semiotic/network/perspective` | **2 KB** | Isometric pictograms and an accessible perspective toggle (the prop ships in ./network) |
| `semiotic/network/perspective/core` | **3 KB** | Projection sizing, resolution, and SVG placement helpers |
| `semiotic/vite` | **1 KB** | Build plugin for unused Semiotic worker assets |
| `semiotic/geo` | **117 KB** | ChoroplethMap, FlowMap, DistanceCartogram, ProportionalSymbolMap |
| `semiotic/wordcloud` | **131 KB** | WordCloud, shaped text placement, and portable layouts |
| `semiotic/realtime` | **231 KB** | RealtimeLineChart, RealtimeHistogram, + 4 streaming charts |
| `semiotic/realtime/core` | **230 KB** | Streaming chart types, HOCs, and buffer helpers |
| `semiotic/realtime/react` | **7 KB** | Stream status and synced push hooks |
| `semiotic/server` | **290 KB** | renderChart, renderDashboard, renderToImage, renderToAnimatedGif |
| `semiotic/server/node` | **290 KB** | renderChart, renderDashboard, renderToImage, renderToAnimatedGif |
| `semiotic/server/edge` | **296 KB** | renderChart, renderChartWithEvidence, renderToStaticSVG, renderDashboard |
| `semiotic/utils` | **115 KB** | ThemeProvider, numeric/accessibility audits, serialization — no chart components |
| `semiotic/utils/core` | **106 KB** | Pure theme helpers, numeric/accessibility audits, and serialization |
| `semiotic/utils/react` | **9 KB** | ThemeProvider, useTheme, useReducedMotion, useHighContrast, useStreamStatus |
| `semiotic/recipes` | **119 KB** | Pure layout functions (waffle, marimekko, flextree, dagre, …) |
| `semiotic/recipes/core` | **116 KB** | Pure layout functions (waffle, marimekko, flextree, dagre, …) |
| `semiotic/recipes/react` | **3 KB** | Glyph and React layout-selection helpers |
| `semiotic/themes` | **13 KB** | Theme presets only (tufte, carbon, etc.) |
| `semiotic/themes/core` | **13 KB** | Theme presets and token helpers |
| `semiotic/themes/react` | **9 KB** | ThemeProvider/useTheme and hooks |
| `semiotic/data` | **5 KB** | bin, rollup, groupBy, pivot, fromVegaLite |
| `semiotic/value` | **6 KB** | BigNumber — focal-value KPI / scorecard (SingleValueFrame POC) |
| `semiotic/physics` | **192 KB** | GaltonBoardChart, EventDropChart, UnitPileChart, CollisionSwarmChart, PacketFlowChart, PhysicsCustomChart |
| `semiotic/physics/matter` | **1 KB** | Matter.js migration helpers + optional peer guard (no chart components) |
| `semiotic/physics/rapier` | **1 KB** | Rapier peer guard + adapter decision metadata (no chart components) |
| `semiotic/ai` | **710 KB** | All schema-backed charts + validation — optimized for LLM code generation |
| `semiotic/ai/core` | **151 KB** | suggestCharts, auditData, describeChart, repairChartConfig, tool adapters — no chart components |
| `semiotic/controls` | **19 KB** | DirectManipulationControl, CircularBrush, LinearBrush, MobileStandardControls, auditVisualizationControls — no frame renderer |
| `semiotic/rough` | **3 KB** | Optional deterministic Rough.js paint backend — exact Semiotic geometry remains authoritative |
| `semiotic/text` | **2 KB** | Optional Pretext annotation hook — peer package excluded |
| `semiotic` | **451 KB** | Full chart API and shared utilities |
### Cold-consumer named imports
The table above is **first-party artifact cost**, not an application bundle. The generated table
below measures a different thing: a fresh consumer bundles one retained named import from a packed
`semiotic` tarball through the public export path, with code splitting as an application build does.
**Initial load** is what a page downloads before the chart renders; **on demand** is code fetched
only when a feature needs it. It includes Semiotic and its resolved runtime dependencies,
but externalizes React/React DOM and optional adapter peers that the host application owns. Each row
starts cold, so use it to compare one public import choice—not to add together an application's rows.
The checked machine-readable baseline is `benchmarks/setup/cold-consumer-imports.json`; refresh it
after a production build with `npm run docs:cold-consumer`.
Method: fresh `npm pack --ignore-scripts` tarball → temporary consumer → minified/tree-shaken Rolldown (Vite's bundler) ESM build with code splitting and a production `NODE_ENV` → gzip -9 per file. **Initial load** counts the entry and its statically imported chunks; **on demand** counts chunks fetched only when a feature needs them (brushing, marginal graphics, animated transitions, a bare frame's built-in layouts). **Everything** is the same build with code splitting disabled: the ceiling if every optional feature loads. React/React DOM and optional adapter peers are external; Semiotic and its resolved runtime dependencies are included. The committed baseline also records a single-file esbuild build of each row.
| Public named import | Runtime | gzip initial load | gzip on demand | gzip everything |
|---|---:|---:|---:|---:|
| `import { semioticVite } from "semiotic/vite"` | node | **0.6 KiB** | — | 0.6 KiB |
| `import { getNetworkPerspectiveSize } from "semiotic/network/perspective/core"` | browser | **1.1 KiB** | — | 1.1 KiB |
| `import { MotifBraidChart } from "semiotic/atlas"` | browser | **112.6 KiB** | 30.4 KiB | 139.4 KiB |
| `import { prepareNetworkAtlas } from "semiotic/atlas/core"` | browser | **7.1 KiB** | — | 7.1 KiB |
| `import { LineChart } from "semiotic"` | browser | **126.7 KiB** | 44.4 KiB | 154.4 KiB |
| `import { LineChart } from "semiotic/xy"` | browser | **126.4 KiB** | 32.5 KiB | 154.4 KiB |
| `import { LineChart } from "semiotic/line"` | browser | **126.3 KiB** | 32.6 KiB | 154.0 KiB |
| `import { BarChart } from "semiotic/ordinal"` | browser | **107.2 KiB** | 14.7 KiB | 122.0 KiB |
| `import { SankeyDiagram } from "semiotic/network"` | browser | **122.4 KiB** | 23.3 KiB | 141.0 KiB |
| `import { ZoomableNetworkCustomChart } from "semiotic/network/zoom"` | browser | **115.9 KiB** | 30.3 KiB | 142.5 KiB |
| `import { isometricGlyphs } from "semiotic/network/perspective"` | browser | **1.4 KiB** | — | 1.4 KiB |
| `import { RealtimeLineChart } from "semiotic/realtime"` | browser | **126.7 KiB** | 43.2 KiB | 154.2 KiB |
| `import { RingBuffer } from "semiotic/realtime/core"` | browser | **0.7 KiB** | 13.5 KiB | 0.7 KiB |
| `import { useStreamStatus } from "semiotic/realtime/react"` | browser | **0.8 KiB** | — | 0.8 KiB |
| `import { GaltonBoardChart } from "semiotic/physics"` | browser | **97.0 KiB** | 2.7 KiB | 99.4 KiB |
| `import { MATTER_PHYSICS_CAPABILITIES } from "semiotic/physics/matter"` | browser | **0.1 KiB** | — | 0.1 KiB |
| `import { RAPIER_PHYSICS_CAPABILITIES } from "semiotic/physics/rapier"` | browser | **0.2 KiB** | — | 0.2 KiB |
| `import { renderChart } from "semiotic/server"` | node | **310.1 KiB** | — | 310.1 KiB |
| `import { generateFrameSVGs } from "semiotic/server/edge"` | node | **128.7 KiB** | — | 128.7 KiB |
| `import { renderToImage } from "semiotic/server/node"` | node | **310.5 KiB** | 0.6 KiB | 311.1 KiB |
| `import { suggestCharts } from "semiotic/ai"` | browser | **32.7 KiB** | 13.5 KiB | 33.9 KiB |
| `import { suggestCharts } from "semiotic/ai/core"` | browser | **32.4 KiB** | — | 32.4 KiB |
| `import { buildArtifactContract } from "semiotic/artifact"` | browser | **4.5 KiB** | — | 4.5 KiB |
| `import { ArtifactInspector } from "semiotic/artifact/react"` | browser | **3.7 KiB** | — | 3.7 KiB |
| `import { createChartAccessContract } from "semiotic/access"` | browser | **29.3 KiB** | — | 29.3 KiB |
| `import { toEvidenceEnvelope } from "semiotic/evidence"` | browser | **44.8 KiB** | — | 44.8 KiB |
| `import { bin } from "semiotic/data"` | browser | **0.9 KiB** | — | 0.9 KiB |
| `import { ChoroplethMap } from "semiotic/geo"` | browser | **109.7 KiB** | 1.7 KiB | 110.6 KiB |
| `import { WordCloud } from "semiotic/wordcloud"` | browser | **111.0 KiB** | 39.9 KiB | 145.8 KiB |
| `import { usePretextAnnotations } from "semiotic/text"` | browser | **1.5 KiB** | — | 1.5 KiB |
| `import { createRoughRenderMode } from "semiotic/rough"` | browser | **3.1 KiB** | — | 3.1 KiB |
| `import { resolveThemePreset } from "semiotic/themes"` | browser | **2.6 KiB** | — | 2.6 KiB |
| `import { resolveThemePreset } from "semiotic/themes/core"` | browser | **2.6 KiB** | — | 2.6 KiB |
| `import { ThemeProvider } from "semiotic/themes/react"` | browser | **5.7 KiB** | — | 5.7 KiB |
| `import { validateProps } from "semiotic/utils"` | browser | **11.4 KiB** | — | 11.4 KiB |
| `import { smartTickFormat } from "semiotic/utils/core"` | browser | **1.0 KiB** | — | 1.0 KiB |
| `import { useReducedMotion } from "semiotic/utils/react"` | browser | **0.3 KiB** | — | 0.3 KiB |
| `import { waffleLayout } from "semiotic/recipes"` | browser | **1.6 KiB** | — | 1.6 KiB |
| `import { waffleLayout } from "semiotic/recipes/core"` | browser | **1.6 KiB** | — | 1.6 KiB |
| `import { Glyph } from "semiotic/recipes/react"` | browser | **0.8 KiB** | — | 0.8 KiB |
| `import { BigNumber } from "semiotic/value"` | browser | **5.9 KiB** | — | 5.9 KiB |
| `import { DirectManipulationControl } from "semiotic/controls"` | browser | **1.5 KiB** | — | 1.5 KiB |
**Line-boundary interpretation:** the retained named import from `semiotic/line` emits 373.4 KiB raw versus 373.4 KiB from `semiotic/xy`; gzip differs by 0.1 KiB (0.1%). Tree-shaking converges both paths on the same LineChart implementation graph. Treat `semiotic/line` as a narrower API/direct-ESM artifact boundary, not an application-bundle saving. Do not add another per-chart entry until its packed named import beats the family path by both 10 KiB gzip and 7%.
**d3 packaging model:** Semiotic externalizes the twelve d3 modules it imports
and declares them as normal runtime dependencies. Consumers do not need to
install d3 packages manually; their bundler resolves, deduplicates, and
tree-shakes that dependency graph. A packed webpack comparison favored this
model in three of four representative chart families, and a Next 16 webpack
route was 22.7 KiB gzip smaller than the fully bundled alternative. The one
bundled win, Sankey, was only 0.4 KiB gzip. This choice retains a 22-package,
1.9 MB unpacked d3 install closure in exchange for smaller common application
graphs and an ordinary dependency contract. The checked policy is
`npm run check:d3-packaging`; the reproducible evidence is in
`benchmarks/setup/d3-packaging.json` and can be regenerated with
`npm run measure:d3-packaging -- --toolchain-root ` after installing
webpack and Next in that isolated toolchain directory.
```jsx
// Import from the sub-path, not from "semiotic"
import { LineChart } from "semiotic/xy"
import { BarChart } from "semiotic/ordinal"
import { SankeyDiagram } from "semiotic/network"
import { ChoroplethMap } from "semiotic/geo"
```
**Tree-shaking & multi-subpath imports**: Family entries (`semiotic/xy`, `semiotic/network`, `semiotic/ai`, …) are built as one ESM graph with **shared chunks**. Stream frames, renderers, and other common code ship once and are imported by every entry that needs them — so combining `semiotic/ai` + `semiotic/xy` + `semiotic/network` does **not** mean paying for three full copies of the runtime. The package is marked `"sideEffects": false`, so modern bundlers keep only the named exports you retain (e.g. `LineChart` + `suggestCharts`). Prefer family subpaths for clarity; import AI helpers from `semiotic/ai` or the lighter `semiotic/ai/core` when you do not need the chart catalog.
**When to use `"semiotic"`**: Fine when you want one import for mixed families. Shared chunks prevent duplicated runtime code across family subpaths; the cold-consumer table above is the better guide for a single named import.
**CommonJS compatibility note:** `require("semiotic/xy")` loads the shared
CommonJS client bundle (about 2.1 MB before compression) so React contexts stay
singletons across family imports. Prefer ESM imports in browser builds when
bundle size matters; splitting that CJS client without a context-identity
contract would be unsafe.
## TypeScript
Built with `strict: true`. Full type definitions ship with the package.
Generics for type-safe accessors:
```tsx
interface Sale { month: number; revenue: number }
data={sales}
xAccessor="month" // TS validates this is keyof Sale
yAccessor="revenue"
/>
```
## Server-Side Rendering
All chart components render SVG automatically in server environments — no
special imports or configuration needed. Non-streaming chart HOCs can be
imported and rendered directly from a Next.js Server Component: Semiotic's
`"use client"` directive defines the package boundary, so the importing page
does not need its own wrapper or directive. Props crossing that boundary must
remain serializable; add an app-owned client wrapper only when you introduce
hooks, callback props, browser state, or a push-driven streaming chart.
```jsx
// app/dashboard/page.tsx — a Next.js Server Component
import { LineChart } from "semiotic/xy"
// Server: renders