echarts-for-react

the simplest, and the best react wrapper for apache echarts. using visualization with mcp server mcp-server-chart.

install

$ npm install --save echarts-for-react

# `echarts` is the peerdependence of `echarts-for-react`, you can install echarts with your own version.
$ npm install --save echarts

then use it.

import reactecharts from 'echarts-for-react';

// render echarts option.
<reactecharts option={this.getoption()} />

you can run website.

$ git clone git@github.com:hustcc/echarts-for-react.git

$ npm install

$ 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/

import react from 'react';
import reactecharts from 'echarts-for-react';  // or var reactecharts = require('echarts-for-react');

<reactecharts
  option={this.getoption()}
  notmerge={true}
  lazyupdate={true}
  theme={"theme_name"}
  onchartready={this.onchartreadycallback}
  onevents={eventsdict}
  opts={}
/>

import echarts.js modules manually to reduce bundle size

with echarts.js v5:

import react from 'react';
// import the core library.
import reactechartscore from 'echarts-for-react/lib/core';
// import the echarts core module, which provides the necessary interfaces for using echarts.
import * as echarts from 'echarts/core';
// import charts, all with chart suffix
import {
  // linechart,
  barchart,
  // piechart,
  // scatterchart,
  // radarchart,
  // mapchart,
  // treechart,
  // treemapchart,
  // graphchart,
  // gaugechart,
  // funnelchart,
  // parallelchart,
  // sankeychart,
  // boxplotchart,
  // candlestickchart,
  // effectscatterchart,
  // lineschart,
  // heatmapchart,
  // pictorialbarchart,
  // themeriverchart,
  // sunburstchart,
  // customchart,
} from 'echarts/charts';
// import components, all suffixed with component
import {
  // gridsimplecomponent,
  gridcomponent,
  // polarcomponent,
  // radarcomponent,
  // geocomponent,
  // singleaxiscomponent,
  // parallelcomponent,
  // calendarcomponent,
  // graphiccomponent,
  // toolboxcomponent,
  tooltipcomponent,
  // axispointercomponent,
  // brushcomponent,
  titlecomponent,
  // timelinecomponent,
  // markpointcomponent,
  // marklinecomponent,
  // markareacomponent,
  // legendcomponent,
  // legendscrollcomponent,
  // legendplaincomponent,
  // datazoomcomponent,
  // datazoominsidecomponent,
  // datazoomslidercomponent,
  // visualmapcomponent,
  // visualmapcontinuouscomponent,
  // visualmappiecewisecomponent,
  // ariacomponent,
  // transformcomponent,
  datasetcomponent,
} from 'echarts/components';
// import renderer, note that introducing the canvasrenderer or svgrenderer is a required step
import {
  canvasrenderer,
  // svgrenderer,
} from 'echarts/renderers';

// register the required components
echarts.use(
  [titlecomponent, tooltipcomponent, gridcomponent, barchart, canvasrenderer]
);

// the usage of reactechartscore are same with above.
<reactechartscore
  echarts={echarts}
  option={this.getoption()}
  notmerge={true}
  lazyupdate={true}
  theme={"theme_name"}
  onchartready={this.onchartreadycallback}
  onevents={eventsdict}
  opts={}
/>

with echarts.js v3 or v4:

import react from 'react';
// import the core library.
import reactechartscore from 'echarts-for-react/lib/core';

// then import echarts modules those you have used manually.
import echarts from 'echarts/lib/echarts';
// import 'echarts/lib/chart/line';
import 'echarts/lib/chart/bar';
// import 'echarts/lib/chart/pie';
// import 'echarts/lib/chart/scatter';
// import 'echarts/lib/chart/radar';

// import 'echarts/lib/chart/map';
// import 'echarts/lib/chart/treemap';
// import 'echarts/lib/chart/graph';
// import 'echarts/lib/chart/gauge';
// import 'echarts/lib/chart/funnel';
// import 'echarts/lib/chart/parallel';
// import 'echarts/lib/chart/sankey';
// import 'echarts/lib/chart/boxplot';
// import 'echarts/lib/chart/candlestick';
// import 'echarts/lib/chart/effectscatter';
// import 'echarts/lib/chart/lines';
// import 'echarts/lib/chart/heatmap';

// import 'echarts/lib/component/graphic';
// import 'echarts/lib/component/grid';
// import 'echarts/lib/component/legend';
import 'echarts/lib/component/tooltip';
// import 'echarts/lib/component/polar';
// import 'echarts/lib/component/geo';
// import 'echarts/lib/component/parallel';
// import 'echarts/lib/component/singleaxis';
// import 'echarts/lib/component/brush';

import 'echarts/lib/component/title';

// import 'echarts/lib/component/datazoom';
// import 'echarts/lib/component/visualmap';

// import 'echarts/lib/component/markpoint';
// import 'echarts/lib/component/markline';
// import 'echarts/lib/component/markarea';

// import 'echarts/lib/component/timeline';
// import 'echarts/lib/component/toolbox';

// import 'zrender/lib/vml/vml';

// the usage of reactechartscore are same with above.
<reactechartscore
  echarts={echarts}
  option={this.getoption()}
  notmerge={true}
  lazyupdate={true}
  theme={"theme_name"}
  onchartready={this.onchartreadycallback}
  onevents={eventsdict}
  opts={}
/>

for next.js user, code transpilation is needed. for next.js 13.1 or higher, as all next-transpile-modules features are natively built-in and the package has been deprecated, so please add transpilepackages: ['echarts', 'zrender'] into nextconfig object:

// next.config.js
/** @type {import('next').nextconfig} */

const nextconfig = {
  // ...existing properties,
  transpilepackages: ['echarts', 'zrender'],
}

module.exports = nextconfig

for next.js with version < 13.1:

// next.config.js
const withtm = require("next-transpile-modules")(["echarts", "zrender"]);

module.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.

• replacemerge (optional, string | string[])

when setoption, default is null. 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.

// import echarts
import echarts from 'echarts';
...
// register theme object
echarts.registertheme('my_theme', {
  backgroundcolor: '#f4cccc'
});
...
// render the echarts use option `theme`
<reactecharts
  option={this.getoption()}
  style={{height: '300px', width: '100%'}}
  classname='echarts-for-echarts'
  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:

const onevents = {
  'click': this.onchartclick,
  'legendselectchanged': this.onchartlegendselectchanged
}
...
<reactecharts
  option={this.getoption()}
  style={{ height: '300px', width: '100%' }}
  onevents={onevents}
/>

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.

<reactecharts
  option={this.getoption()}
  style={{ height: '300px' }}
  opts={{renderer: 'svg'}} // use svg to render the chart.
/>

• 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:

// render the echarts component below with rel
<reactecharts
  ref={(e) => { this.echartref = e; }}
  option={this.getoption()}
/>

// then get the `reactecharts` use this.echarts_react

const echartinstance = this.echartref.getechartsinstance();
// then you can use any api of echarts.
const base64 = echartinstance.getdataurl();

typescript and useref() example:

const getoption = () => {/** */};

export default function app() {
	const echartsref = useref<instancetype<typeof reactecharts>>(null);

	useeffect(() => {
		if (echartsref.current) {
			const echartsinstance = echartsref.current.getechartsinstance();
			// do something
			echartsinstance.resize();
		}
	}, []);
	return <reactecharts ref={echartsref} option={getoption()} />;
}

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:

<reactecharts
  option={this.getoption()}
  style={{height: '300px'}}
  opts={{renderer: 'svg'}} // use svg to render the chart.
/>

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

npm install --save echarts-gl

import 'echarts-gl'
import reactecharts from "echarts-for-react";

<reactecharts
  option={gl_option}
/>

license

mit@hustcc.