Semiotic

A React data visualization library designed for AI-assisted development and streaming data.

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, maintain a live chart, or correct a published chart. The source task packets identify their build and evidence scope; source availability does not establish installed or deployed parity.

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 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 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 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 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

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, combining the Semiotic config, JSX, reader grounding, diagnostics, accessibility audit, and optional rendered SVG/image evidence:

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:

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 has a larger ecosystem and more community examples. Need GPU-accelerated rendering for millions of data points? Apache ECharts 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.

Install

npm install semiotic

Requires React 18.1+ or React 19.

Quick Examples

Coordinated Dashboard

Hover one chart and highlight the same data in another through a shared selection:

import { LinkedCharts, Scatterplot, BarChart } from "semiotic"

Streaming Metrics with Decay

Live data fades old points, flashes new ones, flags stale feeds:

import { RealtimeLineChart } from "semiotic"

const chartRef = useRef() chartRef.current.push({ time: Date.now(), value: cpuLoad })

Network Graphs

Force-directed graphs and Sankey diagrams — same API as LineChart:

import { ForceDirectedGraph, SankeyD