API reference

The entire public surface of mates-charts: one component, one atom factory, two theme hooks and the Highcharts re-export.

Exports

Export	Kind	Description
`Chart`	component	Renders a Highcharts instance bound to a chart atom. Factory to interpolate in `html` templates.
`chartAtom`	factory	Wraps `Highcharts.Options` in a reactive mates atom. Safe to call at module scope.
`useThemeAtomWithHighcharts`	hook	Wires the mates theme to `Highcharts.setOptions` — light/dark defaults on every change. Idempotent.
`useAdaptiveTheme`	hook	Returns a shared atom of the resolved theme (`"light" \| "dark"`, never `"auto"`).
`Highcharts`	value	The Highcharts core instance — for `setOptions`, namespaces and factories.

Entry points: "mates-charts" (core + the most-used modules, auto-registered) and "mates-charts/core" (bare core, zero modules). "mates-charts/modules" registers the full Tier-A set explicitly.

Chart(chart, options?)

Prop	Type	Default	Description
`chart`	`ChartAtomType`	required	Reactive options atom created by `chartAtom(…)`.
`options.theme`	`"light" \| "dark" \| (() => "light" \| "dark")`	follows themeAtom	Per-chart theme override. A getter is re-evaluated reactively — `"auto"` resolves via `themeAtom.resolved`.

The rendered root is a div at width:100%; height:100% — size it from the parent container.

chartAtom(config) → ChartAtomType

Member	Description
`atom() / .get()`	Reactive read of the current `Highcharts.Options` — registers a dependency when called inside a render/effect scope.
`.set(options \| updater)`	Replace the config (or derive from the previous one). Mounted charts re-run `chart.update(config, true, true)`.
`.update(fn)`	In-place mutation — allowed because the config is deliberately not frozen (Highcharts mutates it internally).
`.val`	Non-reactive snapshot.

How it maps to Highcharts

mates-charts	Highcharts equivalent
`chartAtom(opts)`	`Highcharts.Options` — the same object, wrapped in a reactive atom
`Chart(atom)`	`Highcharts.chart(el, opts)` on mount, plus lifecycle teardown
`atom.set(opts)`	`chart.update(opts, true, true)` — automatic
`useThemeAtomWithHighcharts()`	`Highcharts.setOptions(theme)` on every theme change

Everything else — titles, axes, legends, tooltips, plotOptions, responsive rules — is the Highcharts 12 API, unchanged. The Highcharts demo gallery is also a mates-charts recipe book: paste any demo's options into chartAtom(…).

Beyond the wrapper — the Highcharts escape hatch

mates-charts re-exports the full Highcharts namespace, so nothing is locked away. Whatever Highcharts can do, you can do — imperatively, alongside the reactive API.

Escape hatch

import { Highcharts, chartAtom } from "mates-charts";

// 1 · global defaults — fonts, colours, locale
Highcharts.setOptions({
    chart: { style: { fontFamily: "Inter, sans-serif" } },
});

// 2 · a custom series type from the registry
const SeriesRegistry = Highcharts.SeriesRegistry;
// …extend any series prototype and register it — it then works via
// chartAtom({ series: [{ type: "mySeries", … }] })

// 3 · factory access for imperative charts outside mates templates
const chart = Highcharts.chart(document.getElementById("mini"), {
    series: [{ data: [1, 2, 3] }],
});

Chart instances are also reachable per component — pass chart.events in the config and the handlers receive the instance (this), as shown in the dynamic charts family.