react-use-echarts

中文 | English

React hooks & component for Apache ECharts — TypeScript, auto-resize, themes, lazy init.

Features

• Hook + Component — use useEcharts hook or the declarative <EChart /> component
• TypeScript first — complete type definitions with IDE autocomplete
• Zero dependencies — no runtime deps beyond peer deps
• Auto-resize — handles container resizing via ResizeObserver
• Themes — built-in light, dark, and macarons themes, plus any custom theme
• Chart linkage — connect multiple charts for synchronized interactions
• Lazy initialization — defer chart init until element enters viewport
• StrictMode safe — instance cache with reference counting handles double mount/unmount

Requirements

• React 19+ (react + react-dom)
• ECharts 6.x

Note: CSR only. ECharts requires DOM access, so SSR is not supported.

Installation

npm install react-use-echarts echarts
# or
yarn add react-use-echarts echarts
# or
pnpm add react-use-echarts echarts

Quick Start

<EChart /> Component

The simplest way — no ref needed:

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

function MyChart() {
  return (
    <EChart
      option={{
        xAxis: { type: "category", data: ["Mon", "Tue", "Wed", "Thu", "Fri"] },
        yAxis: { type: "value" },
        series: [{ data: [150, 230, 224, 218, 135], type: "line" }],
      }}
    />
  );
}

Pass ref to access { setOption, getInstance, resize } imperatively.

useEcharts Hook

For full control, use the hook directly:

import { useRef } from "react";
import { useEcharts } from "react-use-echarts";

function MyChart() {
  const chartRef = useRef<HTMLDivElement>(null);
  const { setOption, getInstance, resize } = useEcharts(chartRef, {
    option: { series: [{ type: "line", data: [150, 230, 224, 218, 135] }] },
  });
  return <div ref={chartRef} style={{ width: "100%", height: "400px" }} />;
}

Recipes

Themes

Built-in themes require one-time registration at app startup:

import { registerBuiltinThemes } from "react-use-echarts/themes/registry";
registerBuiltinThemes();

// Built-in theme
useEcharts(chartRef, { option, theme: "dark" });

// Any string registered via echarts.registerTheme
useEcharts(chartRef, { option, theme: "vintage" });

// Custom theme object (use useMemo to keep reference stable)
const customTheme = useMemo(() => ({ color: ["#fc8452", "#9a60b4", "#ea7ccc"] }), []);
useEcharts(chartRef, { option, theme: customTheme });

Event Handling

Supports shorthand (function) and full config (object with query/context):

useEcharts(chartRef, {
  option,
  onEvents: {
    click: (params) => console.log("Clicked:", params),
    mouseover: {
      handler: (params) => console.log("Hover:", params),
      query: "series",
    },
  },
});

Loading State

const [loading, setLoading] = useState(true);

useEcharts(chartRef, {
  option,
  showLoading: loading,
  loadingOption: { text: "Loading..." },
});

Chart Linkage

Assign the same group ID — tooltips, highlights, and other interactions will sync:

useEcharts(chartRef1, { option: option1, group: "dashboard" });
useEcharts(chartRef2, { option: option2, group: "dashboard" });

Lazy Initialization

Defer chart init until the element scrolls into view:

useEcharts(chartRef, { option, lazyInit: true });

// Custom IntersectionObserver options
useEcharts(chartRef, {
  option,
  lazyInit: { rootMargin: "200px", threshold: 0.5 },
});

Gotchas

• Container needs explicit size — the chart won't render in a zero-height div; give the container height (and width if not 100%).
• Keep onEvents reference stable — a new onEvents object on each render triggers a full rebind. Memoize it with useMemo (or hoist) when handlers don't change.
• Don't share one DOM element across multiple useEcharts hooks — the instance cache reuses a single ECharts instance and emits a dev warning; updates from different hooks will overwrite each other.
• initOpts and custom theme objects recreate the instance on reference change — pass memoized or module-level constants unless recreation is intended.
• StrictMode is safe — double mount/unmount is handled by the reference-counted instance cache.

API Reference

<EChart /> Props

Declarative component wrapping useEcharts. Accepts all hook options as props plus:

useEcharts(ref, options)

Options

Returns

Other Exports

import { useLazyInit } from "react-use-echarts"; // standalone lazy init hook
import { isBuiltinTheme, registerCustomTheme } from "react-use-echarts"; // theme utils (no JSON)
import { registerBuiltinThemes } from "react-use-echarts/themes/registry"; // ~20KB theme JSON

// All exported types: UseEchartsOptions, UseEchartsReturn, EChartProps,
// EChartsEvents, EChartsEventConfig, EChartsInitOpts, BuiltinTheme, LoadingOption
// EChartsOption and SetOptionOpts come from the "echarts" package directly.

Contributing

We welcome all contributions. Please read the contributing guidelines first.

Changelog

Detailed changes for each release are documented in the release notes.

License

MIT © Ethan