@opendata-ai/openchart

Publication-quality data graphics from a JSON spec. You describe what the chart should communicate, and the engine handles scales, label placement, accessibility, and responsive layout. The result reads like a polished infographic, not a developer's debug output.

The spec is a plain JSON object that both humans and LLMs can author. The headless engine means the same spec renders in React, Vue, Svelte, or vanilla JS without code changes.

Interactive Examples

Quick start

npm install @opendata-ai/openchart-react

import { Chart } from "@opendata-ai/openchart-react";

const spec = {
  mark: "bar",
  data: [
    { language: "Python", popularity: 29 },
    { language: "JavaScript", popularity: 24 },
    { language: "TypeScript", popularity: 17 },
    { language: "Java", popularity: 14 },
    { language: "Go", popularity: 10 },
  ],
  encoding: {
    x: { field: "popularity", type: "quantitative" },
    y: { field: "language", type: "nominal" },
  },
  chrome: {
    title: "Python leads developer mindshare",
    subtitle: "2024 developer survey results",
    source: "Source: Stack Overflow",
  },
};

function App() {
  return (
    <div style={{ width: 600, height: 400 }}>
      <Chart spec={spec} />
    </div>
  );
}

That's the whole interface. encoding maps data fields to visual channels. chrome adds editorial framing. The engine figures out the rest.

The fixed-height wrapper is optional. Without one, the chart sizes itself: a 400px budget for the visualization (axes + plot), and titles, legends, and other chrome grow the figure on top of that. Give the wrapper an explicit height when you need the chart to fit a fixed slot.

Features

Category	What you get
Charts	Bar, line, area, point, circle, arc (pie/donut), lollipop, beeswarm, range, waffle, calendar, parliament
Tables	Sort, search, pagination, heatmap cells, sparklines, inline bars, category colors
Graphs	Force-directed networks, canvas rendering, node interaction, search, zoom
Maps	Choropleth and symbol maps from TopoJSON, plus US state tile grids
Flow	Sankey diagrams for multi-stage flows
Layout	Layered specs, faceting / small multiples, bar lists
Motion	Entrance animations, data-update transitions, scrollytelling stories
Chrome	Title, subtitle, source, byline, footer
Annotations	Reference lines, highlighted ranges, text callouts
Themes	Deep-mergeable config for colors, fonts, spacing. Dark mode: auto, force, or off
A11y	Auto-generated alt text, ARIA labels, keyboard navigation, screen reader tables
Responsive	Breakpoint-aware layout with adaptive label density, legend position, and placement
Rendering	SVG by default, automatic canvas promotion for dense scatter
Export	SVG, PNG, JPG, CSV, and GIF (via the optional gifenc peer)

Tables are a first-class visualization type with heatmaps, sparklines, inline bars, and more.

Installation

Use case	Install
React	npm install @opendata-ai/openchart-react
Vue 3	npm install @opendata-ai/openchart-vue
Svelte 5	npm install @opendata-ai/openchart-svelte
Vanilla JS / any framework	npm install @opendata-ai/openchart-vanilla
Types only / custom renderer	npm install @opendata-ai/openchart-core @opendata-ai/openchart-engine

Each package re-exports the types you need, so you typically only install one.

Release candidates publish under the next dist-tag, so a plain install always gets the latest stable. To try one: npm install @opendata-ai/openchart-react@next.

Documentation

Doc	What's in it
Getting started	Hands-on tutorial from first chart to custom themes, tables, and graphs
Chart types	Catalog of every mark and spec type, with when to reach for each
Spec reference	Field-by-field type reference for ChartSpec, TableSpec, and GraphSpec
Tables	Column config, sparklines, heatmap cells, sorting and pagination
Graphs	Force-directed network layout, node/link encoding, interaction
Ranking and change	Patterns for showing movement, deltas, and rank shifts
Generating specs	Building specs programmatically and from LLM output
Integration guide	Events, controlled tables, export, responsive behavior, vanilla JS lifecycle
Accessibility	What's automatic, what's opt-in (alt text, pattern fills, contrast warnings), WCAG mapping
Agent patterns	Visualization patterns and cookbook for LLM-generated charts
Architecture	Compilation pipeline, package boundaries, design decisions
Migrating to v8	Breaking changes, before/after specs, and jq codemod recipes for the v8 upgrade
Theming tokens	Design token system, TokenValue light/dark pairs, seriesStrategy, named presets
Contributing	Setup, running tests, adding chart types, PR guidelines

Packages

@opendata-ai/openchart-core       Types, theme, colors, a11y, locale (no DOM)
@opendata-ai/openchart-engine     Headless compiler: spec in, layout out (no DOM)
@opendata-ai/openchart-vanilla    DOM rendering: SVG charts, maps, sankey, tilemaps,
                                  HTML tables, bar lists, canvas graphs (+ ./story, ./gif)
@opendata-ai/openchart-react      React wrappers with lifecycle management
@opendata-ai/openchart-vue        Vue 3 wrappers with lifecycle management
@opendata-ai/openchart-svelte     Svelte 5 wrappers with lifecycle management

Dependency direction: core <- engine <- vanilla <- react / vue / svelte. No lateral imports.

Claude Code skill

If you use Claude Code, the OpenChart skill gives Claude knowledge of the spec grammar, encoding rules, and design best practices so it can generate publication-quality specs from your data.

/plugin marketplace add tryopendata/skills
/plugin install openchart@openchart
/openchart

Or reference it in your Claude Code rules and prompts: Skill(openchart:openchart)

Part of the OpenData ecosystem

OpenChart is the visualization layer for OpenData, an open source platform for discovering, exploring, and visualizing public datasets. If you're looking for data to chart, that's a good place to start.

License

Apache 2.0