Getting started

mochart draws animated, interactive SVG charts from two plain inputs: a config object describing the chart and a dataset. No framework is required — the core library manipulates the DOM directly through a retained-mode renderer, and updates write only the attributes that changed.

Install

npm install @mochart/core

Using a framework? Install its binding instead and get automatic container sizing on top of the same API: Angular, Lit, React, Svelte, or Vue.

The optional stylesheet

Charts style themselves with inline styles, so no CSS import is required. The package does ship one optional stylesheet:

import '@mochart/core/mochart.css';

It re-asserts the browser default styles that the chart's HTML overlays (the tooltip and the message overlays) rely on. Import it when your page uses a global CSS reset — Tailwind's preflight, VitePress's base styles, or a normalize.css-style reset — which can otherwise disturb overlay layout (for example, svg { display: block } wraps the tooltip's color icon onto its own line). It never overrides the chart's own styling, and overlays still inherit your page's font and text color.

Your first chart

createDefaultChart is the simplest entry point — give it a container element, a raw config, and an array-of-objects dataset:

Open in demo ↗

import { createDefaultChart } from '@mochart/core';

const config = {
  title: { text: 'Monthly Revenue' },
  categoryAxis: { property: 'month', type: 'string', scale: 'ordinal' },
  seriesDefaults: { renderer: 'bar' },
  series: [{ property: 'revenue', title: 'Revenue' }]
};

const data = [
  { month: 'Jan', revenue: 12 },
  { month: 'Feb', revenue: 18 },
  { month: 'Mar', revenue: 15 },
  { month: 'Apr', revenue: 24 },
  { month: 'May', revenue: 21 },
  { month: 'Jun', revenue: 28 }
];

const chart = createDefaultChart(document.getElementById('chart'), {
  config,
  data,
  width: 640,
  height: 400
});

Three things to notice:

• categoryAxis.property and each series' property name the dataset fields to read — the category value and the series values.
• An optional version pins the config format — worth including in configs you store or share, so migrateConfig can upgrade them if the format changes (validation).
• Everything else is optional. Axes, legend, tooltip, crosshair, and animation all come with defaults; the config reference documents every property.

Updating and destroying

The returned ChartHandle:

chart.update({ data: nextData });   // animates to the new data
chart.update({ width, height });    // re-layout at a new size
chart.update({ config: nextConfig }); // config changes animate too
chart.refresh();                    // re-read data that was mutated in place
chart.destroy();                    // cancel tweens, remove the chart's DOM

update merges new props into the chart and detects changes by object identity: pass a new data array or config object — mutating the previous one in place is not detected. If you do mutate your data in place, call refresh to re-read it. (There is also replace, which swaps the whole prop set at once, for hosts that pass every prop on every render.)

When animation is enabled (the default), data and config changes — and refresh — animate through mochart's staged animation phases — try the button under the chart above. Size changes are the exception: a new width/height re-lays the chart out instantly.

The lower-level entry point

createChart skips the conveniences: it takes an already-enhanced config and an explicit data provider, for hosts that manage those themselves:

import { createChart, enhanceConfig, ArrayOfObjectsDataProvider } from '@mochart/core';

const mochartConfig = enhanceConfig(config);
const dataProvider = new ArrayOfObjectsDataProvider(data, 'month');

const chart = createChart(container, { mochartConfig, dataProvider, width: 640, height: 400 });

See The config model for what "enhanced" means and Data providers for the provider interface.

Browser support

Mochart targets modern evergreen browsers (Chrome/Edge, Firefox, Safari); the published builds are ES modules (plus an IIFE bundle for script tags, dist/mochart.iife.js, exposing the global mochart) targeting ES2020. Everything the core uses — SVG rendering, SVG text measurement (getBBox, getComputedTextLength) for layout and truncation, and requestAnimationFrame for animation — is baseline in that set, so no polyfills are required. Build-free static HTML examples of both flavors — script tag and ES module — live in packages/mochart/example.

A few boundaries worth knowing:

• ResizeObserver is used only by the framework bindings, and only to track the container when width/height are omitted. It is feature-detected: without it, charts with explicit sizes are unaffected — omitted dimensions just stop tracking the container.
• Server-side rendering — the core createChart/createDefaultChart need a real DOM; do not call them during server rendering. All five framework bindings are SSR-safe out of the box: on the server they render only their container (or nothing) and mount the chart in the browser (React defers to an effect, Angular checks PLATFORM_ID, Lit's directive falls back to its no-DOM render path, and Vue/Svelte mount hooks are client-only).
• Test environments — jsdom has no SVG layout engine; shim getBBox/getComputedTextLength/getSubStringLength to return zero sizes and the chart takes its documented default-bounds fallbacks (the binding test suites show the shims).
• Export — @mochart/export additionally uses XMLSerializer, Blob/URL.createObjectURL, and (for PNG) a 2D canvas decoding an SVG image — all baseline in the supported browsers. Exports inline the chart's computed styles but do not embed font files: an exported SVG renders with whatever fonts the viewer has, and a PNG rasterizes with the fonts loaded on the exporting page.

Where to go next

• The config model — how config sections, shared *Defaults sections, defaults, and validation fit together
• Staged animation — what animates, in what order, and how to tune it
• Interaction — focus, legend filtering, tooltip, crosshair, and the callback props
• Accessibility — the keyboard map, screen-reader behavior, and reduced-motion support, on by default and tuned via the accessibility config section
• Theming and dark mode — chart chrome follows your page's CSS color, dark mode included
• Exporting images — download any chart as a standalone SVG or PNG file
• Recipes — working configs for common chart shapes
• The demo galleries (Vanilla, Angular, Lit, React, Svelte, Vue) — browse dozens of demo charts and edit their configs and data live