Charts

Generate a chart as an SVG string, then pass it to an <img> in your document. Takumi renders the SVG without running the chart library in a browser. The library must support generating SVG in your runtime.

Render an ECharts chart

Install ECharts alongside takumi-js:

npm i echarts takumi-js @takumi-rs/helpers react

This example generates a bar chart and saves it as a PNG. ECharts uses its SVG server renderer, so it needs no DOM or canvas.

import * as echarts from "echarts";
import { render } from "takumi-js";
import { googleFonts } from "@takumi-rs/helpers";
import { writeFile } from "node:fs/promises";

const chart = echarts.init(null, null, {
  renderer: "svg",
  ssr: true,
  width: 560,
  height: 360,
});

chart.setOption({
  animation: false,
  textStyle: { fontFamily: "Inter" },
  xAxis: { type: "category", data: ["Q1", "Q2", "Q3", "Q4"] },
  yAxis: { type: "value" },
  series: [{ type: "bar", data: [320, 730, 550, 910] }],
});

const svg = chart.renderToSVGString();
chart.dispose();

const fonts = (await googleFonts(["Inter"])).map((font) => ({ ...font, ranges: [] }));
const png = await render(
  <img
    src={svg}
    alt="Quarterly revenue: 320, 730, 550, and 910"
    style={{ width: 560, height: 360 }}
  />,
  { width: 560, height: 360, fonts },
);

await writeFile("revenue.png", png);

Keep animation: false for static output. Animated SVG can capture an empty or partially drawn chart. Dispose of the ECharts instance after extracting the SVG.

The SVG string goes directly in src. It does not need an images entry. To include it in an HTML string, insert the SVG markup inside the document.

For PDF output, see Charts in PDF.

Fonts for chart labels

Register fonts that cover every label, tick, and legend entry. Set the chart's font family to the same name.

googleFonts() returns font subsets with Unicode ranges. Takumi filters those subsets against text in the document tree, which excludes text inside an SVG image. Clearing ranges, as above, keeps every returned subset.

For a large font family, select the subsets against the chart text first. Include generated numeric ticks and punctuation as well as your data labels:

import { googleFonts, subsetFonts } from "@takumi-rs/helpers";

const chartText = "一月二月三月四月營收0123456789.,−-%";
const fonts = subsetFonts({
  fonts: await googleFonts(["Noto Sans TC"]),
  source: chartText,
}).map((font) => ({ ...font, ranges: [] }));

Pass fonts to render() and set ECharts textStyle.fontFamily to "Noto Sans TC". For offline output, load bundled font bytes instead. See Fonts in CI and offline renders.

Use another chart library

Takumi accepts the SVG output, not the library's interactive component. Generate the final chart before calling render().

A library that requires a DOM or canvas needs its own server rendering setup. If it produces a PNG, pass that image to Takumi instead. A raster chart remains raster in PDF.