react-use-echarts

中文 | English

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

📊 Live demo & interactive playground →

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

Why react-use-echarts?

A modern, hook-first wrapper for teams on React 19 + ECharts 6. ECharts stays the single source of truth — you pass EChartsOption straight through, with no abstraction layer to re-learn.

| | react-use-echarts | echarts-for-react | | ------------- | ------------------------------------------------- | ------------------------ | | API | useEcharts hook and <EChart /> component | Component only | | Built for | React 19 — callback ref, StrictMode-safe | React 16–18 era | | Auto-resize | ResizeObserver + RAF, on by default | ✓ | | Lazy init | Built-in lazyInit (IntersectionObserver) | Manual | | Chart linkage | Built-in group prop | Manual echarts.connect | | Error routing | onError for chart operations and imperative API | Manual try/catch | | Format & deps | ESM-only, tree-shakeable, zero runtime deps | CJS + ESM, zero deps |

Already using echarts-for-react? Most props map 1:1 — see Migrating from echarts-for-react.

Requirements

• React 19.2+ (react + react-dom) — useEffectEvent is used internally and reached stable in 19.2
• ECharts 6.x
• Node.js 22.13+ (required by the package metadata for installation and build tooling; the runtime chart code remains browser-only ESM)

CSR only. ECharts needs a live DOM; SSR is not supported.

ESM-only since 1.3.0. The package publishes ESM entries for the main API (dist/index.js) plus the preset-full and themes/registry subpaths. Every modern bundler (Vite, Next.js, webpack 5+, Rspack, Parcel, Turbopack) and Node 22+ (require(ESM)) consume them natively. If you still depend on CJS-only tooling, pin to 1.2.x.

Installation

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

Register ECharts modules

Since v2.1 react-use-echarts is fully modular — it does not auto-register any ECharts chart, component, renderer or feature. Call one of the registrars below once at your application entry, before the first chart renders:

// Simplest — registers everything ECharts ships with (~370 KB gzip with ECharts 6.1;
// exact size varies by ECharts version and bundler).
import { registerEchartsFull } from "react-use-echarts/preset-full";
registerEchartsFull();

Or, for tree-shake-friendly production builds, register only what you actually render — see Tree-shaking for the recipe.

Why? The default react-use-echarts entry imports only echarts/core, so it does not force the full ECharts surface into every consumer bundle. Explicit registration lets each app choose the one-line full preset or a smaller selective module list.

Quick Start

1. Register ECharts Once

For the fastest start, register the full ECharts surface at your app entry:

// main.tsx / index.tsx
import { registerEchartsFull } from "react-use-echarts/preset-full";

registerEchartsFull();

For production bundles that only render a few chart types, replace this with selective echarts.use([...]) registration later; the chart API stays the same.

2. Render a Chart

The simplest component path — no ref needed:

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

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

The chart container must have an explicit size. The example above sets it on <EChart />; if you keep the default { width: "100%", height: "100%" }, make sure the parent has an explicit height.

Pass ref to access the imperative API — see Returns for the full list (setOption, dispatchAction, clear, resize, appendData, getDataURL, convertToPixel, …).

3. Use the Hook Directly

For full control, use the hook directly. It returns a callback ref to attach to your container plus a reactive instance field and the full imperative API:

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

function MyChart() {
  const { ref, instance, setOption, resize } = useEcharts({
    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={ref} style={{ width: "100%", height: "400px" }} />;
}

instance is undefined before init and after dispose; subscribe via useEffect([instance]) to run side effects against the live ECharts instance.

The chart container must have an explicit size, for example 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({ option, theme: "dark" });

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

// Custom theme object (useMemo avoids repeated content-key serialization)
const customTheme = useMemo(() => ({ color: ["#fc8452", "#9a60b4", "#ea7ccc"] }), []);
useEcharts({ option, theme: customTheme });

Note: theme names registered directly via echarts.registerTheme() (like "vintage" above) work, but trigger a one-time dev-only warning because the library cannot see that registration. Prefer registerCustomTheme(name, config) from react-use-echarts — it registers the theme by name through the library, which silences the warning. If you must register via echarts.registerTheme() (e.g. a third-party package does it for you), the warning is safe to ignore as long as registration happens before the chart mounts; it never appears in production builds.

Event Handling

Supports shorthand (function) and full config (object with query/context). Known echarts events have their params type auto-inferred from EChartsEventPayloadMap — no manual cast needed.

useEcharts({
  option,
  onEvents: {
    // `params` is auto-typed as `ECElementEvent`
    click: (params) => console.log("clicked", params.data),
    mouseover: {
      handler: (params) => console.log("hovered", params.value),
      query: "series",
    },
    // `params` is auto-typed as `SelectChangedPayload`
    selectchanged: (params) => console.log("selection changed", params),
  },
});

Custom event names (e.g. registered via echarts.registerAction()) fall through to the open index signature with a loose params type. To get a typed payload for your own events, augment EChartsEventPayloadMap:

declare module "react-use-echarts" {
  interface EChartsEventPayloadMap {
    "my-custom-action": { foo: number; bar: string };
  }
}

Loading State

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

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

Chart Linkage

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

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

Lazy Initialization

Defer chart init until the element scrolls into view:

useEcharts({ option, lazyInit: true });

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

Note: lazy init is a one-shot latch — "lazy" means "defer until first visible", not "track visibility". Once the element has intersected, the chart stays initialized for the hook's lifetime: replacing the container DOM node or toggling lazyInit off and back on does not re-arm observation. To start deferring again, remount the component.

Tree-shaking

The library is fully modular — pick the registration tier that matches your build target:

Tier 1 — All-in-one (development / prototyping). One line, ~370 KB gzip with ECharts 6.1 (exact size varies by version and bundler):

import { registerEchartsFull } from "react-use-echarts/preset-full";
registerEchartsFull();

Tier 2 — Selective (recommended for production). Register only what you render — bundlers tree-shake the rest of ECharts away:

import * as echarts from "echarts/core";
import { LineChart } from "echarts/charts";
import { GridComponent, TooltipComponent } from "echarts/components";
import { CanvasRenderer } from "echarts/renderers";
echarts.use([LineChart, GridComponent, TooltipComponent, CanvasRenderer]);

See examples/selective-registration/SelectiveRegistrationChart.tsx for a runnable demo.

Tier 3 — Existing full-entry registration. If your app already imports the full "echarts" entry, ECharts performs its built-in registrations and you do not need to call registerEchartsFull() as well. Tier 1 makes the full-registration choice explicit; Tier 2 remains the smaller production path.

ECharts maintains a single global registry — echarts.use([...]) and registerEchartsFull() compose freely. You can call them in any order, anywhere in your app, but they must run before the first useEcharts() render.

Use with Next.js (App Router)

The default package entry, preset-full, and themes/registry are marked with "use client", so importing them inside any React Server Component file does not bundle ECharts into the server payload. Wrap the chart in your own client component and import it from any Server Component:

// app/components/MyChart.tsx
"use client";
import { EChart } from "react-use-echarts";
import { registerEchartsFull } from "react-use-echarts/preset-full";

registerEchartsFull();

export function MyChart() {
  return (
    <EChart
      style={{ height: 400 }}
      option={{
        xAxis: { type: "category", data: ["A", "B", "C"] },
        yAxis: { type: "value" },
        series: [{ type: "line", data: [1, 2, 3] }],
      }}
    />
  );
}

// app/page.tsx (Server Component) — imports the Client Component directly
import { MyChart } from "./components/MyChart";

export default function Page() {
  return <MyChart />;
}

Pages Router only: if you need to load the chart inside getServerSideProps / getStaticProps pages and force client-only rendering, use dynamic(() => import("./components/MyChart").then((m) => m.MyChart), { ssr: false }). In the App Router, next/dynamic with ssr: false is disallowed inside Server Components — the "use client" directive already does the right thing.

Gotchas

• Container needs explicit size — the chart won't render in a zero-height div; give the container height (and width if not 100%).
• Forgetting to register ECharts modules — useEcharts() initializes a chart against ECharts' shared global registry, so charts/components/renderers/features must be registered (via registerEchartsFull() or echarts.use([...])) before the first render. A missing registration usually shows up as Renderer 'undefined' is not imported or a chart that silently never paints; see Register ECharts modules. In dev, if init throws … is not a constructor, the library also prints a one-time hint pointing you here.
• Keep onEvents contents stable — inline wrapper objects are deduplicated when their handler/query/context references are unchanged, but inline lambdas create new handlers and trigger a rebind. Memoize or hoist handlers used in frequently-rendered charts.
• 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 are keyed by serialized content — equivalent serializable objects do not recreate the instance, but memoizing avoids repeated serialization and makes intent clear. Never mutate either object in place: the same reference is treated as unchanged.
• option updates are reference-driven — every new option reference calls setOption, while in-place mutation of the same object is not observed. Memoize expensive options when parent renders are frequent, and replace the wrapper object when chart data changes.
• 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:

| Prop | Type | Default | Description | | ----------- | --------------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | style | React.CSSProperties | { width: '100%', height: '100%' } | Container style (merged with defaults) | | className | string | — | Container CSS class | | ref | Ref<EChartHandle> | — | Exposes the imperative API as EChartHandle (Omit<UseEchartsReturn, 'ref'> — the container ref is owned by <EChart> itself) |

All other native div attributes are forwarded to the chart container, including id, role, aria-*, data-*, tabIndex, and DOM event handlers. children and dangerouslySetInnerHTML are excluded because ECharts owns the container contents; onError remains the chart error handler.

useEcharts(options)

Options

| Option | Type | Default | Description | | --------------- | ------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | option | EChartsOption | (required) | ECharts configuration | | theme | string \| object | — | Any registered 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 chart operations and imperative API calls. Without it, effect failures log via console.error; imperative methods rethrow |

Returns

Prefer the declarative props (option, theme, showLoading, …) over imperative methods. Use these methods only when a prop does not cover the action — image export, coordinate conversion, streaming append, etc. All methods are no-ops or return safe defaults when the instance is not yet initialized. When the instance throws, errors are routed through onError if provided (and the call returns the fallback); otherwise the error is rethrown — including from readers (no console.error fallback for imperative methods).

Container ref / live instance

| Property | Type | Description | | ---------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | ref | RefCallback<HTMLDivElement> | Callback ref to attach to the chart container. Compose with your own ref via mergeRefs | | instance | ECharts \| undefined | Reactive — defined after init, undefined before init and after dispose. Subscribe via useEffect([instance]) to run side effects on the live instance |

Lifecycle / updates

| Method | Type | Description | | ---------------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | | setOption | (option: EChartsOption, opts?: SetOptionOpts) => void | Update chart configuration | | dispatchAction | (payload: Payload, opt?: boolean \| { silent?: boolean; flush?: boolean }) => void | Dispatch an ECharts action (highlight, downplay, showTip, etc.) | | clear | () => void | Clear current chart content | | resize | (opts?: ResizeOpts) => void | Manually trigger chart resize. ResizeOpts accepts width/height/animation/silent | | appendData | (params: { seriesIndex: number; data: ArrayLike<unknown> }) => void | Append data to a series (streaming). Invalidates prop-sync bookkeeping so the next relevant reactive update can restore declarative state |

Read / introspect

| Method | Type | Description | | ------------ | ---------------------------------- | ---------------------------------------------------------------------------------------- | | getOption | () => EChartsOption \| undefined | Get the current merged option | | getWidth | () => number \| undefined | Container width in pixels | | getHeight | () => number \| undefined | Container height in pixels | | getDom | () => HTMLElement \| undefined | Underlying DOM container | | isDisposed | () => boolean | Whether the instance is disposed (returns true when uninitialized — semantically gone) |

Export

| Method | Type | Description | | --------------------- | ---------------------------------------------------------- | -------------------------------------------------------- | | getDataURL | (opts?) => string \| undefined | Base64 image data URL (png / jpeg / svg) | | getConnectedDataURL | (opts?) => string \| undefined | Combined image of all charts in the same group | | renderToSVGString | (opts?: { useViewBox?: boolean }) => string \| undefined | Render chart to SVG string (works with the SVG renderer) | | getSvgDataURL | () => string \| undefined | Get SVG data URL of the current chart |

Coordinate conversion

| Method | Type | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- | | convertToPixel | (finder: ChartFinder, value: ChartScaleValue \| Array<ChartScaleValue \| ChartScaleValue[] \| null \| undefined>) => number \| number[] \| undefined | Logical → pixel coordinates | | convertFromPixel | (finder: ChartFinder, value: number \| number[]) => number \| number[] \| undefined | Pixel → logical coordinates | | containPixel | (finder: ChartFinder, value: number[]) => boolean | Whether a pixel point is inside the matched component (false when uninit) |

ChartFinder is string | { seriesIndex?, seriesId?, …, geoIndex?, … } — a string shorthand or a model finder object. ChartScaleValue is number | string | Date.

Other Exports

import { useLazyInit } from "react-use-echarts"; // standalone lazy init hook -> { ref, isInView }
import { mergeRefs } from "react-use-echarts"; // compose multiple refs into one callback ref
import { isBuiltinTheme, isKnownTheme, registerCustomTheme } from "react-use-echarts"; // theme utils (no JSON)
import { registerBuiltinThemes } from "react-use-echarts/themes/registry"; // ~20KB theme JSON
import { registerEchartsFull } from "react-use-echarts/preset-full"; // one-line full-set registrar (see Register ECharts modules)

// All exported types: UseEchartsOptions, UseEchartsReturn, UseLazyInitReturn,
// EChartProps, EChartHandle, EChartsEvents, EChartsEventConfig, EChartsEventHandler,
// EChartsEventPayloadMap, EChartsInitOpts, BuiltinTheme, LoadingOption,
// ChartFinder, ChartScaleValue, Payload.
// EChartsOption, SetOptionOpts, ResizeOpts are also re-exported here for
// convenience (they originate in the "echarts" package), so you can import them
// from react-use-echarts alongside the types above instead of reaching into echarts.

mergeRefs returns a callback ref that fans the node out to every input — RefObject, legacy callback ref, or React 19 callback ref with cleanup — and isolates each invocation so a throwing 3rd-party ref can't strand the chart. Reach for it when you need both the hook-provided ref and your own:

const myRef = useRef<HTMLDivElement>(null);
const { ref } = useEcharts({ option });
return <div ref={mergeRefs(ref, myRef)} style={{ height: 400 }} />;

Migrating from echarts-for-react

Most props map 1:1; a few are folded into existing options. Quick reference:

| echarts-for-react | react-use-echarts | Notes | | ------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | option | option | Same | | theme | theme | Same; built-in themes need registerBuiltinThemes() first (see Themes) | | notMerge / lazyUpdate | setOptionOpts: { notMerge, lazyUpdate } | Folded into a single object passed to setOption | | showLoading | showLoading | Same | | loadingOption | loadingOption | Same | | onEvents | onEvents | Same shape; also accepts { handler, query?, context? } for query/context binding | | onChartReady | Subscribe to the reactive instance | useEffect(() => { if (instance) onReady(instance); }, [instance]) — the returned instance is undefined before init and re-renders when init/dispose completes | | opts.renderer | renderer: 'canvas' \| 'svg' | Promoted to a top-level option | | opts (rest) | initOpts | Same shape (devicePixelRatio, locale, width, height, useDirtyRect, etc.) | | style | style | <EChart /> defaults to { width: '100%', height: '100%' } so the parent needs size | | className | className | Same | | lazyUpdate (top-level) | setOptionOpts: { lazyUpdate: true } | See notMerge row | | shouldSetOption | Gate the option prop yourself | A new option reference triggers setOption; for custom predicates (deep comparison, throttling, app-state gating), memoize or skip the option prop in the parent component | | autoResize (4.x) | autoResize | Same default (true); resize uses ResizeObserver + RAF | | none | lazyInit | New: defer init until the container scrolls into viewport | | none | group | New: chart linkage via shared group ID | | none | onError | New: route chart operation errors through a callback (init, setOption, events, loading, resize, group linkage, and imperative calls) |

Side-by-side example:

// echarts-for-react
<ReactECharts
  option={option}
  theme="dark"
  notMerge
  lazyUpdate
  opts={{ renderer: "svg", devicePixelRatio: 2 }}
  onEvents={{ click: handleClick }}
  showLoading={loading}
  onChartReady={(instance) => instanceRef.current = instance}
/>

// react-use-echarts
<EChart
  ref={chartRef}
  option={option}
  theme="dark"
  setOptionOpts={{ notMerge: true, lazyUpdate: true }}
  renderer="svg"
  initOpts={{ devicePixelRatio: 2 }}
  onEvents={{ click: handleClick }}
  showLoading={loading}
/>
// chartRef.current?.instance replaces onChartReady

Migrating from v2.x

v3 removes the legacy react-use-echarts/core subpath. If you already import from react-use-echarts and already register ECharts modules before the first chart render, no code changes are needed.

If you are upgrading from v2.0's everything-included default entry, or from an app that still relied on import "echarts" side effects, add one registration call at your application entry:

// app entry (e.g. main.tsx, index.tsx)
import { registerEchartsFull } from "react-use-echarts/preset-full";
registerEchartsFull();

That call is equivalent to v2.0's automatic ECharts registration and gives you the same everything-included experience (~370 KB gzip with ECharts 6.1; exact size varies by version and bundler). For production builds that only render a few chart types, replace it with a selective echarts.use([...]) — see Tree-shaking.

Replace any remaining from "react-use-echarts/core" imports with from "react-use-echarts".

Migrating from v1

v2.0 flips the hook to return a callback ref + reactive instance, aligning with the modern community convention used by floating-ui/react, react-aria, downshift, and react-hook-form. <EChart /> external props are unchanged — only direct hook consumers and <EChart ref> typings migrate.

| v1 | v2 | Notes | | ------------------------------------------------ | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | const ref = useRef(); useEcharts(ref, options) | const { ref } = useEcharts(options) | Hook owns the callback ref; attach it to your container | | getInstance() method on the hook return | instance field on the same return | Reactive — re-renders when init/dispose completes; use useEffect([instance]) to subscribe | | useLazyInit(ref, options) returning boolean | useLazyInit(options) returning { ref, isInView } | Same callback-ref pattern | | useRef<UseEchartsReturn>(null) for <EChart> | useRef<EChartHandle>(null) for <EChart> | EChartHandle = Omit<UseEchartsReturn, 'ref'> — the container ref is intentionally not exposed on the imperative handle | | Compose refs by hand | mergeRefs(chartRef, myRef) | New public utility (see Other Exports) | | engines.node >=20 | engines.node >=22 | Tooling requirement only — published bundle is unaffected |

Side-by-side hook example:

// v1
const chartRef = useRef<HTMLDivElement>(null);
const { setOption, getInstance } = useEcharts(chartRef, { option });
useEffect(() => {
  getInstance()?.on("finished", handler);
}, []);
return <div ref={chartRef} style={{ height: 400 }} />;

// v2
const { ref, instance, setOption } = useEcharts({ option });
useEffect(() => {
  if (!instance) return;
  instance.on("finished", handler);
  return () => instance.off("finished", handler);
}, [instance]);
return <div ref={ref} style={{ height: 400 }} />;

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