use-echarts-react

A modernized React hook for integrating ECharts.

---

Features

• Hook based modern APIs.
• Supports tree-shakeable ECharts usages by default.
• Supports declarative/imperative mode for different scenarios.
• Supports deep comparison.
• Supports all ECharts APIs.
• Works with SSR.
• Written in Typescript.
• 100% test coverage.

Install

$ npm install --save use-echarts-react echarts

Basic Usage

import { LineChart } from 'echarts/charts';
import { GridComponent, LegendComponent, TitleComponent, TooltipComponent } from 'echarts/components';
import { use } from 'echarts/core';
import { CanvasRenderer } from 'echarts/renderers';
import { useECharts, useEChartsEvent } from "use-echarts-react";

// Tree-shakeable ECharts usage, see https://echarts.apache.org/handbook/en/basics/import/#shrinking-bundle-size.
use([
  CanvasRenderer,
  GridComponent,
  LineChart,
  TooltipComponent,
  TitleComponent,
  LegendComponent
]);

const App = () => {
  const ref = useECharts<HTMLDivElement>({
    // echarts instance option
    xAxis: {
      type: 'category',
      data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
    },
    yAxis: {
      type: 'value'
    },
    series: [
      {
        data: [150, 230, 224, 218, 135, 147, 260],
        type: 'line'
      }
    ]
  }, {
    width: 100,
    height: 100
  });

  // binding event
  useEChartsEvent(ref, 'click', () => {
    console.log('triggered');
  });

  return (
    <div ref={ref}></div>
  );
};

APIs

useECharts(option, initOpts)

Configures the ECharts instance with the provided options.

option (Optional)

This parameter is used for configuring the ECharts instance with the options that would be passed to the setOption method. It can include the following:

Property	Description
... ECharts Options	Accepts all options from setOption method. Refers ECharts Configuration Items Manual for all available options.
group	Specifies the group of the ECharts instance and automatically connects the chart group. See echartsInstance.group.
loading	Controls the loading state of the ECharts instance. See showLoading method.

initOpts (Optional)

This is used to initialize the ECharts instance. It can only be set once during the initialization and includes the following options:

Property	Description
theme	The theme for the ECharts instance, see echarts.init - theme.
locale	The locale for the ECharts instance, see echarts.init - locale.
renderer	The renderer for ECharts (canvas or SVG), see echarts.init - renderer.
devicePixelRatio	The pixel ratio for the instance, see echarts.init - devicePixelRatio.
useDirtyRect	Whether to use the dirty rectangle technique to optimize performance, see echarts.init - useDirtyRect.
useCoarsePointer	Whether to use a coarse pointer for event handling, see echarts.init - useCoarsePointer.
pointerSize	The size of the pointer for interactions, see echarts.init - pointerSize.
ssr	Enable server-side rendering for the instance, see echarts.init - ssr.
width	The width of the chart, see echarts.init - width.
height	The height of the chart, see echarts.init - height.
resize	Automatically resizes the chart when the bound element’s size changes. Defaults to false.
imperativeMode	Enables direct control of the ECharts instance. When enabled, the option parameter is ignored. Defaults to false.
deepCompare	Enables deep comparison for option before updating the instance. Defaults to false.

Returns

The hook returns a React ref object used to bind the DOM element. This ref contains two properties:

• current: The current DOM element that the ref is bound to.
• chart: The current created ECharts instance with restricted APIs. If imperativeMode is enabled, this will return the complete ECharts instance, allowing direct interaction with all methods of ECharts.

useEChartsEvent(ref, event, handler) / useEChartsEvent(ref, event, query, handler)

Automatically handling event binding to ECharts instance.

ref (Required)

The return value of the useECharts hook.

event (Required)

The event to listen for. This is the same as the eventName parameter in the ECharts echartsInstance.on method.

query (Optional)

This is the query parameter for the event listener. It is the same as the query parameter in the ECharts echartsInstance.on method.

handler (Required)

Same as the handler parameter in the ECharts echartsInstance.on method.

Declarative / Imperative Mode

By default, useECharts will return an ECharts instance with restricted APIs like setOption, on... and user should update ECharts instance by updating the hook parameters. Also user can get a complete ECharts instance via enabling imperativeMode.

Declarative Mode

import { useECharts } from "use-echarts-react";

const App = () => {
  const ref = useECharts<HTMLDivElement>({
    // can only use hook parameters to update ECharts instance.
    xAxis: {
      type: 'category',
      data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
    },
    yAxis: {
      type: 'value'
    },
    series: [
      {
        data: [150, 230, 224, 218, 135, 147, 260],
        type: 'line'
      }
    ]
  }, {
    width: 100,
    height: 100
  });

  return (
    <div ref={ref}></div>
  );
};

Imperative Mode

import { useECharts } from "use-echarts-react";

const App = () => {
  const ref = useECharts<HTMLDivElement>({
    // option will be ignored under imperative mode.
  }, {
    imperativeMode: true,
    width: 100,
    height: 100
  });

  return (
    <div>
      <button
        onClick={() => {
          // `setOption` is available to call now.
          ref.chart?.setOption({
            xAxis: {
              type: 'category',
              data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
            },
            yAxis: {
              type: 'value'
            },
            series: [
              {
                data: [150, 230, 224, 218, 135, 147, 260],
                type: 'line',
              }
            ]
          });
        }}
      >
        update
      </button>
      <div ref={ref}></div>
    </div>
  );
};

About SSR

useEcharts supports using ECharts SSR option. But this is not as the same as React SSR. ECharts SSR is used for returning SVG string instead of manipulating a dom element.

import { useECharts } from "use-echarts-react";

const App = () => {
  const ref = useECharts<HTMLDivElement>({
    xAxis: {
      type: 'category',
      data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
    },
    yAxis: {
      type: 'value'
    },
    series: [
      {
        data: [150, 230, 224, 218, 135, 147, 260],
        type: 'line'
      }
    ]
  }, {
    renderer: 'svg',
    ssr: true,
    width: 100,
    height: 100
  });

  return (
    <div
      dangerouslySetInnerHTML={{
        __html: ref.chart?.renderToSVGString() ?? ''
      }}
    ></div>
  );
};

License

MIT License