react-use-echarts

中文 | English

A React hooks library for Apache ECharts with full TypeScript support. Simple, lightweight, and gets out of your way.

Features

• Hook + Component — use useEcharts hook or the declarative <EChart /> component
• TypeScript first — written in TypeScript with complete type definitions
• Zero dependencies — no runtime deps beyond peer deps: react, react-dom, and echarts
• Auto-resize — handles container resizing via ResizeObserver
• Themes — built-in light, dark, and macarons themes, plus custom theme support
• Chart linkage — connect multiple charts for synchronized interactions
• Lazy initialization — defer chart init until element enters viewport
• Event handling — flexible event system with shorthand and full config modes
• Loading state — built-in loading indicator management
• Error handling — optional onError callback with deterministic fallback behavior
• StrictMode safe — instance cache with reference counting handles double mount/unmount

Requirements

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

Note: This library is designed for client-side rendering (CSR) only. Server-side rendering (SSR) is not supported as ECharts requires DOM access.

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" }],
      }}
    />
  );
}

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: {
      xAxis: { type: "category", data: ["Mon", "Tue", "Wed", "Thu", "Fri"] },
      yAxis: { type: "value" },
      series: [{ data: [150, 230, 224, 218, 135], type: "line" }],
    },
  });

  return <div ref={chartRef} style={{ width: "100%", height: "400px" }} />;
}

Recipes

Event Handling

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

useEcharts(chartRef, {
  option,
  onEvents: {
    // Shorthand — just pass a function
    click: (params) => console.log("Clicked:", params),
    // Full config — when you need query or context
    mouseover: {
      handler: (params) => console.log("Hover:", params),
      query: "series",
    },
  },
});

Loading State

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

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

Themes

Built-in: light, dark, macarons. Or pass a custom theme object:

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

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

useEcharts(chartRef, { option, theme: customTheme });

Chart Linkage

Connect charts by assigning 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. Ideal for pages with many charts:

// Use defaults (rootMargin: '50px', threshold: 0.1)
useEcharts(chartRef, { option, lazyInit: true });

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

SVG Renderer

useEcharts(chartRef, { option, renderer: "svg" });

Accessing ECharts Instance

Use getInstance() for advanced operations like exporting images:

const { getInstance } = useEcharts(chartRef, { option });

const exportImage = () => {
  const instance = getInstance();
  if (instance) {
    const url = instance.getDataURL({ type: "png", pixelRatio: 2, backgroundColor: "#fff" });
    const link = document.createElement("a");
    link.download = "chart.png";
    link.href = url;
    link.click();
  }
};

Error Handling

useEcharts(chartRef, {
  option,
  onError: (error) => console.error("Chart error:", error),
});

Without onError: init / first setOption failures are reported with console.error; option-update or imperative setOption failures are rethrown.

Using the Component Ref

Access hook return values through the component ref:

import { useRef } from "react";
import { EChart } from "react-use-echarts";
import type { UseEchartsReturn } from "react-use-echarts";

function MyChart() {
  const chartRef = useRef<UseEchartsReturn>(null);

  return (
    <div>
      <button onClick={() => chartRef.current?.resize()}>Resize</button>
      <EChart ref={chartRef} option={option} style={{ height: "600px" }} className="my-chart" />
    </div>
  );
}

API Reference

<EChart /> Props

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

Prop	Type	Default	Description
style	React.CSSProperties	{ width: '100%', height: '400px' }	Container style (merged with defaults)
className	string	—	Container CSS class
ref	Ref<UseEchartsReturn>	—	Exposes { setOption, getInstance, resize }

useEcharts(ref, options)

Options

Option	Type	Default	Description
option	EChartsOption	(required)	ECharts configuration
theme	'light' | 'dark' | 'macarons' | object | null	null	Theme name or custom theme object
renderer	'canvas' | 'svg'	'canvas'	Renderer type
lazyInit	boolean | IntersectionObserverInit	false	Lazy initialization via IntersectionObserver
group	string	—	Chart linkage group ID
setOptionOpts	SetOptionOpts	—	Default options for setOption calls
showLoading	boolean	false	Show loading indicator
loadingOption	object	—	Loading indicator configuration
onEvents	EChartsEvents	—	Event handlers (fn or { handler, query?, context? })
autoResize	boolean	true	Auto-resize via ResizeObserver
initOpts	EChartsInitOpts	—	Passed to echarts.init() (devicePixelRatio, locale, width, etc.)
onError	(error: unknown) => void	—	Error handler for init/setOption operations

Returns

Method	Type	Description
setOption	(option: EChartsOption, opts?: SetOptionOpts) => void	Update chart configuration
getInstance	() => ECharts | undefined	Get ECharts instance
resize	() => void	Manually trigger chart resize

useLazyInit(ref, options)

Standalone lazy initialization hook based on IntersectionObserver.

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

const isInView = useLazyInit(elementRef, true); // or pass IntersectionObserverInit

Returns boolean — true once the element enters the viewport (or immediately if options is false).

Theme Utilities

import {
  getAvailableThemes, // () => ['light', 'dark', 'macarons']
  isBuiltinTheme, // (name: string) => boolean
  getBuiltinTheme, // (name: BuiltinTheme) => object | null
  registerCustomTheme, // (name: string, config: object) => void
  registerBuiltinThemes, // () => void — manual registration (usually unnecessary)
  ensureBuiltinThemesRegistered, // () => void — idempotent, called automatically
} from "react-use-echarts";

Advanced Utilities

Instance cache and group linkage utilities for advanced use cases:

import {
  // Instance cache — WeakMap-based with reference counting
  getCachedInstance, // (element) => ECharts | undefined
  setCachedInstance, // (element, instance) => ECharts
  replaceCachedInstance, // (element, instance) => ECharts
  releaseCachedInstance, // (element) => void
  getReferenceCount, // (element) => number
  clearInstanceCache, // () => void

  // Group linkage — manual chart group management
  addToGroup, // (instance, groupId) => void
  removeFromGroup, // (instance, groupId) => void
  updateGroup, // (instance, oldGroupId?, newGroupId?) => void
  getGroupInstances, // (groupId) => ECharts[]
  getInstanceGroup, // (instance) => string | undefined
  isInGroup, // (instance) => boolean
  clearGroups, // () => void
} from "react-use-echarts";

Exported Types

import type {
  UseEchartsOptions,
  UseEchartsReturn,
  EChartProps,
  EChartsEvents,
  EChartsEventConfig,
  EChartsInitOpts,
  BuiltinTheme,
} from "react-use-echarts";

Development (Vite+)

This repository is aligned with the Vite+ toolchain:

• vp install — install dependencies (delegates to packageManager, currently pnpm)
• vp dev — run the examples dev server (http://localhost:3000)
• vp check — run format + lint + typecheck
• vp test run --coverage — run tests with coverage
• vp pack — build library artifacts into dist/

package.json also maps core tools to Vite+ packages:

• vite → @voidzero-dev/vite-plus-core
• vitest → @voidzero-dev/vite-plus-test

CI and release workflows use voidzero-dev/setup-vp plus vp commands for install/check/build.

Contributing

We welcome all contributions. Please read our contributing guidelines first. You can submit ideas as pull requests or GitHub issues.

Changelog

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

License

MIT © Ethan