echarts-for-react-fc

English | 中文

Using ECharts in React, encapsulating it within a functional component, and providing a hook for consumers to consume.

Given echarts-for-react, why would you still need to write this component?

echarts-for-react provides parameters for updating charts using the setOption method on the component, but this can feel uncomfortable and awkward.
Any internal changes in echarts are actually unrelated to React, so it's better to keep using static parameters in props for chart initialization and use the chart instance to update the chart.
The props of this component are only used for chart initialization, and any chart updates are performed by obtaining the echarts instance through a ref and using the setOption method. With the built-in useChart hook, users don't need to worry about whether the chart is ready or not; they can directly use setOption and the timing of updates is determined within the hook.

Different from echarts-for-react

1. This component is written using hooks.
2. This component is developed and intended for use only with echarts v5. Compatibility with other versions of echarts is unknown.

hooks

useChart

Usage:
See the example below.
Purpose:
With the built-in useChart, users don't need to worry about whether the chart is ready or not. They can directly set options, and the update timing is determined within the hook.

useTooltip

Usage:
See a complete example below.
Purpose:
Allows React to take over the rendering inside the ECharts tooltip.

Use

A simple usage approach is to utilize the provided useChart hook, without needing to consider any timing concerns. You can obtain the echarts instance through a ref and directly use the setOption method, while letting the hook handle the rendering timing. Alternatively, you can provide a ref, echarts, and onChartReady function to obtain the echarts instance, allowing for customization.

a simple example.

import { useEffect } from 'react';

import * as echarts from 'echarts/core';
import { GridComponent } from 'echarts/components';
import { LineChart } from 'echarts/charts';
import { CanvasRenderer } from 'echarts/renderers';

import EChartsReact, { useChart } from 'echarts-for-react-fc';

echarts.use([GridComponent, LineChart, CanvasRenderer]);

const style = {
  width: '100%',
  height: 300,
};

const Simple = () => {
  const { chartRef, setChartOption, handleListenChartReady } = useChart();

  useEffect(() => {
    setChartOption({
      xAxis: {
        type: 'category',
        data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'],
      },
      yAxis: {
        type: 'value',
      },
      series: [
        {
          id: 1,
          data: [150, 230, 224, 218, 135, 147, 260],
          type: 'line',
        },
      ],
    });

    setTimeout(() => {
      setChartOption({
        series: [
          {
            id: 2,
            data: [400, 130, 224, 118, 35, 47, 260],
            type: 'line',
          },
        ],
      });
    }, 2000);
  }, []);

  return (
    <EChartsReact
      style={style}
      ref={chartRef}
      echarts={echarts}
      onChartReady={handleListenChartReady}
    />
  );
};

export default Simple;

a complete exmaple.

import { FC, useCallback, useEffect, useMemo, useState } from 'react';
import * as echarts from 'echarts/core';
import { GridComponent, TooltipComponent } from 'echarts/components';
import { LineChart } from 'echarts/charts';
import { UniversalTransition } from 'echarts/features';
import { CanvasRenderer, SVGRenderer } from 'echarts/renderers';

import EChartsReact, { useChart, useTooltip ,CreateTooltipFn } from 'echarts-for-react-fc';

echarts.use([
  GridComponent,
  TooltipComponent,
  LineChart,
  CanvasRenderer,
  SVGRenderer,
  UniversalTransition,
]);

const style = {
  width: '100%',
  height: 300,
};

const createTooltipFn: CreateTooltipFn = ({ params }) => {
  if (Array.isArray(params)) {
    return (
      <div>
        {params.map((item) => (
          <div>{item.name}</div>
        ))}
      </div>
    );
  } else {
    return <div>{params.name}</div>;
  }
};

const Complete: FC = () => {
  const { chartRef, setChartOption, handleListenChartReady } = useChart();

  const { tooltipDom, tooltipRender, createTooltip } = useTooltip({
    component: createTooltipFn,
  });

  const [renderer, setRenderer] = useState<'canvas' | 'svg'>('canvas');

  useEffect(() => {
    setChartOption({
      tooltip: {
        formatter: (params) => {
          setTimeout(() => {
            createTooltip({ params });
          }, 100);
          return tooltipDom;
        },
      },
      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',
        },
      ],
    });
  }, []);

  const handleClickToggleRenderer = useCallback(() => {
    setRenderer((oldRenderer) => (oldRenderer === 'canvas' ? 'svg' : 'canvas'));
  }, []);

  const initOpts = useMemo(() => {
    return {
      renderer: renderer,
    };
  }, [renderer]);

  return (
    <>
      <p> now renderer: {renderer}</p>
      <button onClick={handleClickToggleRenderer}>toggle theme</button>
      <EChartsReact
        ref={chartRef}
        initOpts={initOpts}
        style={style}
        echarts={echarts}
        onChartReady={handleListenChartReady}
      ></EChartsReact>
      {tooltipRender}
    </>
  );
};

export default Complete;

Props

Parameter Name	Description	Type	Required
echarts	echarts	typeof echarts	Y
theme	init fn Parameter: theme	string | object	N
initOpts	init fn Parameter: Initial Configuration	EChartsInitOpts	N
onChartReady	chart ready event	(ready: boolean) => void;	Y
onEvents	Register Event	Record<string, EChartsEventInfo | EChartsEventInfo[]>	N
autoResize	listen window size changes，resize chart	boolean | echarts.ResizeOpts	N
style	DOM style	CSSProperties	N
classname	DOM classname	string	N

Tip

1. Please make sure to set the size of the chart.
2. It is recommended to import echarts using import * as echarts from "echarts/core";, register and use echarts by module. This helps reduce the size of the required packages.

LICENSE

MIT@mmmml-zhao.

Thanks

This component is referenced from echarts-for-react，Thanks to the contributor of the component。