echarts-for-react

The simplest, and the best React wrapper for Apache ECharts.

Install

1$ npm install --save echarts-for-react
2
3# `echarts` is the peerDependence of `echarts-for-react`, you can install echarts with your own version.
4$ npm install --save echarts

Then use it.

1import ReactECharts from 'echarts-for-react';
2
3// render echarts option.
4<ReactECharts option={this.getOption()} />

You can run website.

1$ git clone git@github.com:hustcc/echarts-for-react.git
2
3$ npm install
4
5$ npm start

Then open http://127.0.0.1:8081/ in your browser. or see https://git.hust.cc/echarts-for-react/ which is deploy on gh-pages.

Usage

Code of a simple demo code showed below. For more example can see: https://git.hust.cc/echarts-for-react/

1import React from 'react';
2import ReactECharts from 'echarts-for-react';  // or var ReactECharts = require('echarts-for-react');
3
4<ReactECharts
5  option={this.getOption()}
6  notMerge={true}
7  lazyUpdate={true}
8  theme={"theme_name"}
9  onChartReady={this.onChartReadyCallback}
10  onEvents={EventsDict}
11  opts={}
12/>

Import ECharts.js modules manually to reduce bundle size

With Echarts.js v5:

1import React from 'react';
2// import the core library.
3import ReactEChartsCore from 'echarts-for-react/lib/core';
4// Import the echarts core module, which provides the necessary interfaces for using echarts.
5import * as echarts from 'echarts/core';
6// Import charts, all with Chart suffix
7import {
8  // LineChart,
9  BarChart,
10  // PieChart,
11  // ScatterChart,
12  // RadarChart,
13  // MapChart,
14  // TreeChart,
15  // TreemapChart,
16  // GraphChart,
17  // GaugeChart,
18  // FunnelChart,
19  // ParallelChart,
20  // SankeyChart,
21  // BoxplotChart,
22  // CandlestickChart,
23  // EffectScatterChart,
24  // LinesChart,
25  // HeatmapChart,
26  // PictorialBarChart,
27  // ThemeRiverChart,
28  // SunburstChart,
29  // CustomChart,
30} from 'echarts/charts';
31// import components, all suffixed with Component
32import {
33  // GridSimpleComponent,
34  GridComponent,
35  // PolarComponent,
36  // RadarComponent,
37  // GeoComponent,
38  // SingleAxisComponent,
39  // ParallelComponent,
40  // CalendarComponent,
41  // GraphicComponent,
42  // ToolboxComponent,
43  TooltipComponent,
44  // AxisPointerComponent,
45  // BrushComponent,
46  TitleComponent,
47  // TimelineComponent,
48  // MarkPointComponent,
49  // MarkLineComponent,
50  // MarkAreaComponent,
51  // LegendComponent,
52  // LegendScrollComponent,
53  // LegendPlainComponent,
54  // DataZoomComponent,
55  // DataZoomInsideComponent,
56  // DataZoomSliderComponent,
57  // VisualMapComponent,
58  // VisualMapContinuousComponent,
59  // VisualMapPiecewiseComponent,
60  // AriaComponent,
61  // TransformComponent,
62  DatasetComponent,
63} from 'echarts/components';
64// Import renderer, note that introducing the CanvasRenderer or SVGRenderer is a required step
65import {
66  CanvasRenderer,
67  // SVGRenderer,
68} from 'echarts/renderers';
69
70// Register the required components
71echarts.use(
72  [TitleComponent, TooltipComponent, GridComponent, BarChart, CanvasRenderer]
73);
74
75// The usage of ReactEChartsCore are same with above.
76<ReactEChartsCore
77  echarts={echarts}
78  option={this.getOption()}
79  notMerge={true}
80  lazyUpdate={true}
81  theme={"theme_name"}
82  onChartReady={this.onChartReadyCallback}
83  onEvents={EventsDict}
84  opts={}
85/>

With Echarts.js v3 or v4:

1import React from 'react';
2// import the core library.
3import ReactEChartsCore from 'echarts-for-react/lib/core';
4
5// then import echarts modules those you have used manually.
6import echarts from 'echarts/lib/echarts';
7// import 'echarts/lib/chart/line';
8import 'echarts/lib/chart/bar';
9// import 'echarts/lib/chart/pie';
10// import 'echarts/lib/chart/scatter';
11// import 'echarts/lib/chart/radar';
12
13// import 'echarts/lib/chart/map';
14// import 'echarts/lib/chart/treemap';
15// import 'echarts/lib/chart/graph';
16// import 'echarts/lib/chart/gauge';
17// import 'echarts/lib/chart/funnel';
18// import 'echarts/lib/chart/parallel';
19// import 'echarts/lib/chart/sankey';
20// import 'echarts/lib/chart/boxplot';
21// import 'echarts/lib/chart/candlestick';
22// import 'echarts/lib/chart/effectScatter';
23// import 'echarts/lib/chart/lines';
24// import 'echarts/lib/chart/heatmap';
25
26// import 'echarts/lib/component/graphic';
27// import 'echarts/lib/component/grid';
28// import 'echarts/lib/component/legend';
29import 'echarts/lib/component/tooltip';
30// import 'echarts/lib/component/polar';
31// import 'echarts/lib/component/geo';
32// import 'echarts/lib/component/parallel';
33// import 'echarts/lib/component/singleAxis';
34// import 'echarts/lib/component/brush';
35
36import 'echarts/lib/component/title';
37
38// import 'echarts/lib/component/dataZoom';
39// import 'echarts/lib/component/visualMap';
40
41// import 'echarts/lib/component/markPoint';
42// import 'echarts/lib/component/markLine';
43// import 'echarts/lib/component/markArea';
44
45// import 'echarts/lib/component/timeline';
46// import 'echarts/lib/component/toolbox';
47
48// import 'zrender/lib/vml/vml';
49
50// The usage of ReactEChartsCore are same with above.
51<ReactEChartsCore
52  echarts={echarts}
53  option={this.getOption()}
54  notMerge={true}
55  lazyUpdate={true}
56  theme={"theme_name"}
57  onChartReady={this.onChartReadyCallback}
58  onEvents={EventsDict}
59  opts={}
60/>

For Next.js user, code transpilation is needed.

1// next.config.js
2const withTM = require("next-transpile-modules")(["echarts", "zrender"]);
3
4module.exports = withTM({})

Props of Component

• option (required, object)

the echarts option config, can see https://echarts.apache.org/option.html#title.

• notMerge (optional, object)

when setOption, not merge the data, default is false. See https://echarts.apache.org/api.html#echartsInstance.setOption.

• lazyUpdate (optional, object)

when setOption, lazy update the data, default is false. See https://echarts.apache.org/api.html#echartsInstance.setOption.

• style (optional, object)

the style of echarts div. object, default is {height: '300px'}.

• className (optional, string)

the class of echarts div. you can setting the css style of charts by class name.

• theme (optional, string)

the theme of echarts. string, should registerTheme before use it (theme object format: https://github.com/ecomfe/echarts/blob/master/theme/dark.js). e.g.

1// import echarts
2import echarts from 'echarts';
3...
4// register theme object
5echarts.registerTheme('my_theme', {
6  backgroundColor: '#f4cccc'
7});
8...
9// render the echarts use option `theme`
10<ReactECharts
11  option={this.getOption()}
12  style={{height: '300px', width: '100%'}}
13  className='echarts-for-echarts'
14  theme='my_theme' />

• onChartReady (optional, function)

when the chart is ready, will callback the function with the echarts object as it's paramter.

• loadingOption (optional, object)

the echarts loading option config, can see https://echarts.apache.org/api.html#echartsInstance.showLoading.

• showLoading (optional, bool, default: false)

bool, when the chart is rendering, show the loading mask.

• onEvents (optional, array(string=>function) )

binding the echarts event, will callback with the echarts event object, and the echart object as it's paramters. e.g:

1const onEvents = {
2  'click': this.onChartClick,
3  'legendselectchanged': this.onChartLegendselectchanged
4}
5...
6<ReactECharts
7  option={this.getOption()}
8  style={{ height: '300px', width: '100%' }}
9  onEvents={onEvents}
10/>

for more event key name, see: https://echarts.apache.org/api.html#events

• opts (optional, object)

the opts of echarts. object, will be used when initial echarts instance by echarts.init. Document here.

1<ReactECharts
2  option={this.getOption()}
3  style={{ height: '300px' }}
4  opts={{renderer: 'svg'}} // use svg to render the chart.
5/>

• autoResize (optional, boolean)

decide whether to trigger this.resize when window resize. default is true.

Component API & Echarts API

the Component only has one API named getEchartsInstance.

• getEchartsInstance() : get the echarts instance object, then you can use any API of echarts.

for example:

1// render the echarts component below with rel
2<ReactECharts
3  ref={(e) => { this.echartRef = e; }}
4  option={this.getOption()}
5/>
6
7// then get the `ReactECharts` use this.echarts_react
8
9const echartInstance = this.echartRef.getEchartsInstance();
10// then you can use any API of echarts.
11const base64 = echartInstance.getDataURL();

About API of echarts, can see https://echarts.apache.org/api.html#echartsInstance.

You can use the API to do:

1. binding / unbinding event.
2. dynamic charts with dynamic data.
3. get the echarts dom / dataURL / base64, save the chart to png.
4. release the charts.

FAQ

How to render the chart with svg when using echarts 4.x

Use the props opts of component with renderer = 'svg'. For example:

1<ReactECharts
2  option={this.getOption()}
3  style={{height: '300px'}}
4  opts={{renderer: 'svg'}} // use svg to render the chart.
5/>

How to resolve Error Component series.scatter3D not exists. Load it first.

Install and import echarts-gl module when you want to create a GL instance

1npm install --save echarts-gl

1import 'echarts-gl'
2import ReactECharts from "echarts-for-react";
3
4<ReactECharts
5  option={GL_OPTION}
6/>

LICENSE

MIT@hustcc.