KNIME® Design System – ECharts

This package contains the KNIME Design System integration for Apache ECharts: the KdsECharts Vue component, the useKdsEChartsColors composable, and the generated KDS ECharts themes (light / dark) with all chart tokens resolved to concrete values.

It's published as npm package: @knime/kds-echarts

Development

This package is part of the KNIME Design System monorepo. For setup instructions, see the root README.

Building

pnpm run build          # Build only this package
pnpm run build:theme    # Only regenerate the ECharts themes from the KDS tokens

Results are saved to dist/.

build:theme reads the resolved design tokens from @knime/kds-styles and writes src/theme/generated.ts (gitignored), so @knime/kds-styles must be built first. The repository's postinstall does both in order.

Using ECharts in a Vue application

Install the @knime/kds-echarts npm package as a dependency:

pnpm add @knime/kds-echarts echarts

KdsECharts deliberately registers nothing itself, so the bundle stays tree-shaken — the consumer registers exactly the renderer, charts and components it uses via ECharts' use():

<script setup lang="ts">
import type { EChartsOption } from "echarts";
import { BarChart } from "echarts/charts";
import { GridComponent, TooltipComponent } from "echarts/components";
import { use } from "echarts/core";
import { CanvasRenderer } from "echarts/renderers";

import { KdsECharts } from "@knime/kds-echarts";

use([CanvasRenderer, BarChart, GridComponent, TooltipComponent]);

const option: EChartsOption = {
  xAxis: { type: "category", data: ["Jan", "Feb", "Mar"] },
  yAxis: { type: "value" },
  series: [{ type: "bar", data: [120, 200, 150] }],
};
</script>

<template>
  <KdsECharts :option="option" style="height: 240px" />
</template>

The KDS theme is applied automatically and follows light/dark mode, so an option should generally omit colors and fonts and let the theme drive styling.

Events (@click, @datazoom, @finished, zr:*, …) as well as class and style fall through to the wrapped vue-echarts component. The underlying ECharts instance is exposed as chart for imperative use (dispatchAction, resize, getDataURL, …).

Public exports

| Export | Kind | Description | | --------------------- | ---------- | ----------------------------------------------------------------------------------- | | KdsECharts | component | ECharts chart with the KDS theme applied and light/dark mode handled | | useKdsEChartsColors | composable | Reactive semantic chart colors for explicit per-series coloring | | light / dark | const | The KDS ECharts theme objects (also available from @knime/kds-echarts/theme) | | chartColors | const | The semantic chart colors per mode (also available from @knime/kds-echarts/theme) | | KdsEChartsProps | type | Props of KdsECharts | | KdsEChartsTheme | type | Shape of a KDS ECharts theme object | | KdsChartColors | type | Shape of the semantic chart colors for one mode |

Explicit per-series coloring

The theme's base palette covers series 1–9 in order. For colors it doesn't reach — status hues, label inks drawn on a segment fill, chart controls — use useKdsEChartsColors(), which resolves against the effective dark mode and flips automatically when the mode changes:

<script setup lang="ts">
import { computed } from "vue";

import { KdsECharts, useKdsEChartsColors } from "@knime/kds-echarts";

const colors = useKdsEChartsColors();
const option = computed(() => ({
  xAxis: { type: "category", data: ["Jan", "Feb", "Mar"] },
  yAxis: { type: "value" },
  series: [
    {
      type: "bar",
      data: [120, 200, 150],
      itemStyle: { color: colors.value.series[1] },
    },
    {
      type: "line",
      data: [90, 90, 90],
      lineStyle: { color: colors.value.status.negative },
    },
  ],
}));
</script>

Using the KDS ECharts theme without Vue

Apache ECharts renders to <canvas>/SVG and cannot resolve CSS custom properties or light-dark(), so it needs concrete, per-mode values. The @knime/kds-echarts/theme entry point ships those theme objects with the KDS chart tokens already resolved, and imports neither Vue nor vue-echarts:

import { BarChart } from "echarts/charts";
import { GridComponent, TooltipComponent } from "echarts/components";
import { init, use } from "echarts/core";
import { CanvasRenderer } from "echarts/renderers";

import { dark, fontFaces, light } from "@knime/kds-echarts/theme";

use([CanvasRenderer, BarChart, GridComponent, TooltipComponent]);

// Canvas keeps whatever glyphs it drew with, so wait for the fonts first.
await Promise.all(fontFaces.map((face) => document.fonts.load(face)));

const chart = init(el, dark); // initialise with a theme object
chart.setTheme(light); // swap themes at runtime (e.g. on dark-mode change)

| Export | Description | | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | light | Light-mode ECharts theme (palette, axes, tooltip, text, …) for registerTheme or vue-echarts' theme prop. | | dark | Dark-mode ECharts theme, same shape as light. | | chartColors | Semantic colors the base theme palette doesn't reach (series 1–9, status hues, on-fill inks, controls) per mode, for explicit per-series coloring. | | fontFaces | Every font face the themes draw with, as document.fonts.load() arguments. |

A non-Vue app can skip installing Vue-related dependencies entirely with pnpm overrides:

// package.json (consumer)
{
  "pnpm": {
    "overrides": {
      "vue": "-",
      "vue-echarts": "-",
      "@knime/kds-components": "-",
    },
  },
}

Using with Vitest, Nuxt, or Vite SSR

The published JavaScript imports its CSS as a side effect (e.g. import "./index.css"), which bundlers handle automatically. When the package is instead evaluated by Node's native ESM loader — as Vitest and Vite/Nuxt SSR do by default, since they externalize node_modules — Node has no .css loader and throws Unknown file extension ".css". Configure the consuming project once so @knime/* packages are processed instead of externalized:

// Vitest — vitest.config.ts
export default defineConfig({
  test: { server: { deps: { inline: [/@knime\//] } } },
});

// Vite SSR — vite.config.ts
export default defineConfig({ ssr: { noExternal: [/@knime\//] } });

// Nuxt — nuxt.config.ts
export default defineNuxtConfig({ build: { transpile: [/@knime\//] } });