@tooark/chart

<ark-chart>: an ECharts chart as a Custom Element that follows the page's light/dark theme, with auto-resize and a click event — plus the imperative engine for use without the element.

🌍 Languages: English (this file) · Português

Contents

• Overview
• Installation
• Configuration
• Components
• Usage examples
• Dependencies
• Contributing
• License

📖 Overview

The @tooark/chart package provides:

• ark-chart with the native ECharts option as a JS property, theme (auto follows the page's color-scheme, including runtime toggles), renderer (canvas/svg), height and auto-resize;
• ark-chart-click (bubbles, composed) with the native ECharts params as detail;
• createChart(container, options) engine: setOption, setTheme, resize, resolvedTheme, destroy and the raw chart instance;
• ECharts is a peer dependency: you pick the version (the engine imports the whole echarts package, so it is not tree-shaken).

🔧 Installation

pnpm add @tooark/chart echarts   # echarts is a peer dependency (>= 5)

⚙️ Configuration

Register the element once (browser only); the chart draws its own colors with ECharts' default (light) or built-in dark theme, not the --ark-color-* tokens, so no stylesheet is required — the theme follows the page's color-scheme or the element's theme attribute:

import { registerTooarkChart } from "@tooark/chart";

registerTooarkChart();

In React, Vue or Angular use the tag directly (the framework READMEs show how); a JS property the framework assigns before this call, such as option bound on the tag, is applied when the element upgrades, so the order does not matter.

📦 Components

ark-chart

• Attributes: theme (auto | light | dark, default auto), renderer (canvas | svg), height (CSS length, default 320px), auto-resize ("false" turns it off), testid, aria-label/aria-labelledby (the host becomes role="img" with that name, unless you gave it a role; without them nothing changes, and ECharts' generated description, option.aria, stays available).
• Properties: option (the EChartsOption; assigning re-renders with notMerge), resolvedTheme.
• Events: ark-chart-click with the ECharts params in detail.
• Hooks: the chart container ([part="canvas"]) carries data-ark="chart" and the testid as data-testid.

Engine

• createChart(container, { option, theme?, renderer?, autoResize? }) → { chart, setOption(option, { notMerge }), setTheme(theme), resize(), resolvedTheme(), destroy() }; autoResize (default true) resizes the chart with the container.
• resolveChartTheme(theme, element).
• Types: ArkChartOptions, ArkChartTheme, ArkChartRenderer, ArkChartInstance, EChartsOption (re-exported).

📝 Usage examples

A bar chart that follows the page theme

const chart = document.createElement("ark-chart");
chart.setAttribute("height", "320px");
chart.option = {
  xAxis: { type: "category", data: ["Mon", "Tue", "Wed"] },
  yAxis: { type: "value" },
  series: [{ type: "bar", data: [120, 200, 150] }],
};
chart.addEventListener("ark-chart-click", (event) => {
  console.log((event as CustomEvent).detail.name, (event as CustomEvent).detail.value);
});
document.body.appendChild(chart);

The engine without the element

import { createChart } from "@tooark/chart";

const instance = createChart(document.querySelector("#sales")!, { option, theme: "auto" });
instance.setOption(nextOption, { notMerge: true });
instance.chart.on("legendselectchanged", handler); // raw ECharts API
instance.destroy();

📋 Dependencies

Installed automatically unless marked as peer; peer dependencies are yours to install (the ranges are what the package declares).

| Package | Version | Description | | ---------------------------------------------------------------- | ---------- | --------------------------------------------------------- | | @tooark/tokens | ^1.3.0 | Design tokens (colors, sizes, motion) and primitive types | | tslib | ^2.8.1 | TypeScript runtime helpers | | echarts | >=5 (peer) | Chart engine |

🪪 Contributing

Contributions are welcome! Open issues and pull requests in the Tooark/web-components repository; CONTRIBUTING.md covers the workflow, the commit convention and the checklist. @tooark/chart is released in lockstep with every other @tooark/* package.

📄 License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.