; } ``` `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: ```tsx 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 (use useMemo to keep reference stable) 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. ```tsx 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`: ```ts declare module "react-use-echarts" { interface EChartsEventPayloadMap { "my-custom-action": { foo: number; bar: string }; } } ``` ### Loading State ```tsx 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: ```tsx useEcharts({ option: option1, group: "dashboard" }); useEcharts({ option: option2, group: "dashboard" }); ``` ### Lazy Initialization Defer chart init until the element scrolls into view: ```tsx 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, ~290KB gzip: ```ts 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: ```ts 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`](./examples/selective-registration/SelectiveRegistrationChart.tsx) for a runnable demo. **Tier 3 — Webpack-only legacy.** Webpack tolerates ECharts' non-conforming `sideEffects` field, so plain `import "echarts";` still works in webpack apps but **fails silently under Rolldown/Vite/Rollup** (chart never paints, console shows `TypeError` from zrender's empty painter registry). Prefer Tier 1 or Tier 2 instead. > 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: ```tsx // 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 ( ); } ``` ```tsx // app/page.tsx (Server Component) — imports the Client Component directly import { MyChart } from "./components/MyChart"; export default function Page() { return ; } ``` > **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](#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` 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 ### `` 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` | — | Exposes the imperative API as `EChartHandle` (`Omit` — the container ref is owned by `` itself) | ### `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` | Callback ref to attach to the chart container. Compose with your own ref via [`mergeRefs`](#other-exports) | | `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 }) => void` | Append data to a series (streaming). Drift-aware: drops dedup memory so a subsequent shallow-equal-but-new-ref `option` rerender re-applies setOption | **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 \| ChartScaleValue[]) => 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 ```tsx 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: ```tsx const myRef = useRef(null); const { ref } = useEcharts({ option }); return

; ``` ## 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](#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` | `` 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 | Top-level keys are deduped via `shallowEqual` automatically; for custom predicates (deep compare, throttling, app-state gating) memoize/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: ```tsx // echarts-for-react instanceRef.current = instance} /> // react-use-echarts // 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: ```ts // 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 ~290KB-gzip everything-included experience. For production builds that only render a few chart types, replace it with a selective `echarts.use([...])` — see [Tree-shaking](#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`. `` external props are unchanged — only direct hook consumers and `` 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(null)` for `` | `useRef(null)` for `` | `EChartHandle = Omit` — the container ref is intentionally not exposed on the imperative handle | | Compose refs by hand | `mergeRefs(chartRef, myRef)` | New public utility (see [Other Exports](#other-exports)) | | `engines.node >=20` | `engines.node >=22` | Tooling requirement only — published bundle is unaffected | Side-by-side hook example: ```tsx // v1 const chartRef = useRef(null); const { setOption, getInstance } = useEcharts(chartRef, { option }); useEffect(() => { getInstance()?.on("finished", handler); }, []); return

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

; ``` ## Contributing We welcome all contributions. Please read the [contributing guidelines](CONTRIBUTING.md) first. ## Changelog Detailed changes for each release are documented in the [release notes](https://github.com/chensid/react-use-echarts/releases). ## License [MIT](./LICENSE.txt) © [Ethan](https://github.com/chensid)