Getting started

mates-charts wraps Highcharts in one reactive component. You write standard Highcharts options; the wrapper handles mounting, updating, teardown and theming.

1 · Install

Shell

npm install mates-charts highcharts

Highcharts is a peer dependency — mates-charts never bundles it, so you control the exact version (12.x recommended).

2 · Create your first chart

Wrap any Highcharts options object in chartAtom(…), render Chart(chart) in a mates template, and give the wrapper a height.

App.tsx → MyChart.ts

import { html } from "mates";
import { Chart, chartAtom } from "mates-charts";

const chart = chartAtom({
    chart: {
        type: "column"
    },
    title: {
        text: "Revenue by quarter"
    },
    xAxis: {
        categories: [
            "Q1",
            "Q2",
            "Q3",
            "Q4"
        ]
    },
    yAxis: {
        title: {
            text: "$k"
        }
    },
    series: [
        {
            type: "column",
            name: "Revenue",
            data: [
                180,
                210,
                195,
                240
            ]
        }
    ]
});

// render inside any mates template — give the wrapper a height:
export const MyChart = () =>
    html`<div style="height: 22rem">${Chart(chart)}</div>`;

3 · Optional series modules

Core series (line, spline, area, column, bar, pie, scatter, bubble, waterfall, boxplot) need nothing extra. The most-used add-on modules are already registered for you — importing mates-charts loads Highcharts core plus gauge, solid gauge, polar/radar, ranges, heatmap, tilemap, treemap, sunburst, streamgraph, sankey, dumbbell, lollipop, venn and wordcloud automatically.

main.ts

// everything below is registered by the main entry already:
import { Chart, chartAtom } from "mates-charts";

// everything else is a one-line side-effect import, e.g.:
import "highcharts/modules/networkgraph";
import "highcharts/modules/organization";

No import-order juggling. Every optional module (and the Tier-B add-ons above) loads Highcharts core itself before registering, so import order never matters. Bundle-critical apps can import from mates-charts/core instead — bare core, zero modules — and opt in per feature.

4 · Reactive updates

The atom IS the chart state. Call set(…) with a new options object or update(…) with a mutator — the mounted chart patches itself via chart.update(…) under the hood.

Reactive updates

import { effect } from "mates";

// swap the whole config
salesChart.set({ chart: { type: "bar" }, series: [...] });

// mutate just one part — the chart updates in place
salesChart.update((cfg) => {
    cfg.title!.text = "Q3 revenue";
});

// react to any other atom
effect(() => {
    const year = yearAtom();
    salesChart.set(loadSeriesFor(year));
});

5 · Theming

Call useThemeAtomWithHighcharts() once at your app root and every chart follows the mates light/dark theme automatically. Per-chart overrides and custom palettes are covered on the theming page.