Enabling Apache ECharts in React for Data Visualization | Tania Rascia's Website

Tania Rascia<br>Color

Theme

About Me<br>I'm Tania, software engineer and open-source creator. This is my digital garden. 🌱

Stay Connected<br>Email signupBlueskyRSS feed

Setting Up a Mac?<br>I keep a guide on setting up a new Mac for development.

Making dashboards with charts and graphs is a pretty common part of the front-end developer experience, as well as deciding which JavaScript library to use for data visualization. As you explore all the different options - Recharts, Visx, D3 - you'll see they all do something you want, and lack something you need.

For a while I was using Nivo, a really impressive React component library, but it didn't have some features I needed like drilling down from one graph type into another, so I started looking into Apache ECharts.

This library is open-source, awesome, and incredibly easy to use. However, as of writing, the React component wrapper (echarts-for-react) that someone made is pretty out of date - last updated more than three years ago, and relies on an old version of ECharts that didn't have all the features I was looking for, so I made a tiny little wrapper that can just be imported as a component in a single file..

Demo

ECharts works by creating an option object that holds all the configuration about the graph. That makes it incredibly easy to work with, because it doesn't require separate components for each graph type.

App.js

import { EChart } from './EChart'

export const App = () => {<br>const option = {<br>// ... chart configuration goes here

return EChart option={option} />

Here's a little demo importing the default Line, Bar and Pie type charts.

Installation

Just install the echarts dependency and you're good to go.

npm i echarts

Using ECharts

With just a few methods from the API, you can get this up and running.

ECharts

First you'll need to create a div and use that ref to inject the ECharts instance, then you can initialize the echartInstance with init(). For as long as it exists, you can access the instanced with getInstanceByDom(). When you're done, you can disconnect() from the instance.

Function<br>Description

init<br>Creates an ECharts instance

getInstanceByDom<br>Returns chart instance of dom container

disconnect<br>Disconnects interaction of multiple chart series.

EChart Instance

Once you have an echartsInstance in the DOM, you can use setOption to update the configuration. We'll be able to update this with useEffect in React. When you're done, you can destroy the instance with dispose()

Function<br>Description

setOption<br>Configuration item, data, universal interface, all parameters and data can all be modified through setOption

dispose<br>Destroys chart instance, after which the instance cannot be used any more

Component

To set up the basic Echart component, you can create a ref on an element and initialize the chart on mount using init(). All the configuration of echarts is set in setOption, so whatever option you pass into the component will initialize the chart.

Everything you need to get set up can be handled in these two useEffects.

EChart.js

import React, { useMemo, useRef, useEffect } from 'react'<br>import { init, getInstanceByDom } from 'echarts'

export const EChart = ({<br>option,<br>chartSettings,<br>optionSettings,<br>style = { width: '100%', height: '350px' },<br>...props<br>}) => {<br>const chartRef = useRef(null)

useEffect(() => {<br>// Initialize chart<br>const chart = init(chartRef.current, null, chartSettings)

return () => {<br>chart?.dispose()<br>}, [])

useEffect(() => {<br>// Re-render chart when option changes<br>const chart = getInstanceByDom(chartRef.current)

chart.setOption(option, optionSettings)<br>}, [option])

return div ref={chartRef} style={style} {...props} />

Now you'll have an element that contains the chart and re-renders if the options change.

Events

The component is pretty basic right now, and there's a few things you'll probably want to add. You can create an event handler to pass a click event into the chart like so:

EChart<br>option={option}<br>events={{<br>click: () => {<br>console.log('Click handler!')<br>},<br>}}<br>/>

This enables any type of event and handler you want to add.

import React, { useMemo, useRef, useEffect } from 'react'<br>import { init, getInstanceByDom } from 'echarts'

export const EChart = ({<br>option,<br>chartSettings<br>optionSettings<br>style = { width: '100%', height: '350px' },<br>events = {}, ...props<br>}) => {<br>const chartRef = useRef(null)

useEffect(() => {<br>// Initialize chart<br>const chart = init(chartRef.current, null, chartSettings)

// Set up event listeners for (const [key, handler] of Object.entries(events)) { chart.on(key, (param) => { handler(param) }) }<br>// Return cleanup function<br>return () => {<br>chart?.dispose()<br>}, [])

useEffect(() => {<br>// Re-render chart when option changes<br>const chart = getInstanceByDom(chartRef.current)

chart.setOption(option, optionSettings)<br>}, [option])

return div ref={chartRef} style={style} {...props} />

Resizing

You also might want the...