@chainsys/sab-react-charts

An extended React wrapper for Apache ECharts with full option parity. All chart types and configurations from the ECharts Examples gallery work via a thin React layer over the official ECharts API.

Package: @chainsys/sab-react-charts
Version: 1.0.2
License: MIT

Features

| Feature | Description | |--------|-------------| | Full ECharts option parity | Pass any valid ECharts option; forwarded without modification | | Bundled ECharts (2D) | You do not need to install echarts separately for standard 2D charts | | Events | Attach ECharts event handlers with onEvents | | Loading state | Show loading overlay via loading / loadingType | | Auto resize | ResizeObserver-driven autoResize (on by default) | | Imperative access | Ref API exposes getEchartsInstance() for resize(), getDataURL(), etc. | | Optional 3D support | Use echarts-gl and pass a custom echarts namespace |

Installation

npm install @chainsys/sab-react-charts
# or
yarn add @chainsys/sab-react-charts
# or
pnpm add @chainsys/sab-react-charts

Peer dependencies

Install in your application if not already present:

• react (>= 19.2.0)
• react-dom (>= 19.2.0)
• node (>= 22.21.1)
• typescript (= 5.9.3)

Dependencies (installed automatically)

• echarts is bundled inside this package for 2D charts.

Quick start

import { SabReactCharts } from '@chainsys/sab-react-charts';
import type { EChartsOption } from 'echarts';

const option: EChartsOption = {
  xAxis: { type: 'category', data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'] },
  yAxis: { type: 'value' },
  series: [{ type: 'line', data: [120, 200, 150, 80, 70, 110, 130] }],
};

export function MyChart() {
  return <SabReactCharts option={option} style={{ height: 400 }} />;
}

Props

Options are aligned with ngx-echarts where applicable.

| Prop | Type | Default | Description | |------|------|--------|-------------| | option | EChartsOption \| null | required | Full ECharts option object (all 2D and 3D chart types). | | merge | EChartsOption \| null | — | Extra option merged on top when calling setOption (ngx-echarts parity). | | notMerge | boolean | false | Do not merge with previous option when updating. | | lazyUpdate | boolean | false | Lazy update (e.g. for large data). | | replaceMerge | string[] | — | Replace specified components when updating. | | theme | string \| object | — | Theme name (e.g. 'light', 'dark') or custom theme object for echarts.init(). | | opts | EChartsInitOpts | — | Init options: devicePixelRatio, renderer ('canvas' \| 'svg'), useDirtyRect, useCoarsePointer, pointerSize, width, height, locale, ssr. | | echarts | typeof echarts | default import | Custom echarts namespace (e.g. with echarts-gl registered) for 3D charts. | | style | CSSProperties | — | Container div style (e.g. width, height). | | className | string | — | Container div class name. | | onChartReady | (chart: ECharts) => void | — | Callback when the chart instance is ready. | | onEvents | Record<string, (params: unknown) => void> | — | ECharts event handlers, e.g. { click: (params) => {} }. | | shouldSetOption | (prev, next) => boolean | () => true | Return false to skip calling setOption for a given update. | | loading | boolean \| EChartsLoadingOption | false | Show loading overlay. | | loadingType | string | 'default' | Loading type passed to showLoading(type, opts). | | autoResize | boolean | true | Resize chart when container size changes (ResizeObserver). |

Ref API

Attach a ref to access the ECharts instance:

import { useRef } from 'react';
import { SabReactCharts } from '@chainsys/sab-react-charts';
import type { SabReactChartsRef } from '@chainsys/sab-react-charts';

function MyChart() {
  const chartRef = useRef<SabReactChartsRef>(null);

  const handleResize = () => chartRef.current?.getEchartsInstance().resize();
  const handleExport = () => {
    const url = chartRef.current?.getEchartsInstance().getDataURL({ type: 'png' });
    // use url
  };

  return (
    <>
      <button onClick={handleResize}>Resize</button>
      <button onClick={handleExport}>Export PNG</button>
      <SabReactCharts ref={chartRef} option={option} />
    </>
  );
}

• getEchartsInstance() – Returns the ECharts instance. Use it for resize(), getDataURL(), getOption(), appendData(), clear(), etc. See ECharts API.

useECharts hook

Optional hook for ref + getter:

import { SabReactCharts, useECharts } from '@chainsys/sab-react-charts';

function MyChart() {
  const [chartRef, getInstance] = useECharts();
  return <SabReactCharts ref={chartRef} option={option} />;
}

Chart types and options

All ECharts chart types and options are supported. Pass any valid ECharts option; the wrapper forwards it to ECharts without modification.

2D chart types: line, bar, pie, scatter, radar, map, heatmap, candlestick, gauge, funnel, treemap, graph, sunburst, boxplot, parallel, sankey, themeRiver, custom series, and combo charts (e.g. line + bar).

3D chart types (require echarts-gl): bar3D, line3D, scatter3D, surface, map3D, lines3D. See 3D charts below.

For themes and maps, use the echarts package directly:

import * as echarts from 'echarts';
echarts.registerTheme('myTheme', { ... });
echarts.registerMap('myMap', geoJSON);
// Then use theme="myTheme" or the map in your option

3D charts (echarts-gl, optional)

ECharts is bundled in this package; 3D charts (bar3D, line3D, scatter3D, surface, map3D, lines3D) are not bundled. To use them, install and register echarts-gl and pass the extended echarts via the echarts prop:

npm install echarts-gl

import * as echarts from 'echarts';
import 'echarts-gl';
import { SabReactCharts } from '@chainsys/sab-react-charts';

const option = {
  grid3D: {},
  xAxis3D: {}, yAxis3D: {}, zAxis3D: {},
  series: [{ type: 'bar3D', data: [...] }],
};
<SabReactCharts echarts={echarts} option={option} style={{ height: 400 }} />

License

MIT