React hooks & component for Apache ECharts. CSR only — ECharts requires DOM access, no SSR/SSG.
Peer deps: react 19.2+, react-dom 19.2+, echarts 6.x
Distribution: ESM-only (since 1.3.0). No Node.js requirement for consumers (browser-only ESM); the Node.js range in devEngines.runtime applies only to developing this repo.
Options: option (required), theme, renderer ('canvas'|'svg', default 'canvas'), lazyInit (default false), group, setOptionOpts, showLoading (default false), loadingOption, onEvents, autoResize (default true), initOpts, onError
ref—RefCallback<HTMLDivElement>to attach to the containerinstance—ECharts | undefined(reactive — defined after init, undefined before/after dispose); for anonChartReady-style callback, useuseEffect(() => { if (instance) onReady(instance); }, [instance, onReady])— an<EChart>object ref is imperative-only and does not notifysetOption(option, opts?)— update chart configresize(opts?)— manual resize trigger- Imperative methods:
dispatchAction,clear,appendData,getOption,getDataURL,getConnectedDataURL,renderToSVGString,getSvgDataURL,getWidth,getHeight,getDom,isDisposed,convertToPixel,convertToLayout,convertFromPixel,containPixel(convert methods take an optional coordinate-systemopt, e.g. matrixclamp) - The returned object is referentially stable — its identity only changes when
instanceor the container element changes, so it can go straight into a dependency array
All useEcharts options as props + native div attributes (id, role, aria-*, data-*, DOM events, etc.; excluding children and dangerouslySetInnerHTML) + style (default { width: '100%', height: '100%' }), className, ref (typed Ref<EChartHandle> — same imperative surface as UseEchartsReturn minus the container ref field, which <EChart> owns)
isBuiltinTheme(name),isKnownTheme(name),registerCustomTheme(name, config)— from'react-use-echarts'mergeRefs(...refs)— compose multiple refs (RefObject, legacy callback ref, or React 19 callback ref returning a cleanup) into one callback ref;null/undefinedentries are skipped, and throws are isolated per-ref so a misbehaving 3rd-party ref can't strand the chartregisterBuiltinThemes()— from'react-use-echarts/themes/registry'(separate entry, ~7KB macarons theme JSON)registerEchartsFull()— from'react-use-echarts/preset-full'; one-line registrar that callsecharts.use(...)with every built-in chart, component, renderer and feature. Call once at app entry.useLazyInit(options)→{ ref, isInView }— standalone lazy-init hook; enabled mode defaults torootMargin: '50px'andthreshold: 0.1
- Container needs explicit width/height — chart won't render in a zero-size div
- ECharts modules must be registered before first render — the library does not auto-register anything. Call
registerEchartsFull()at app entry for an everything-included experience, orecharts.use([...])selectively for tree-shake-friendly builds. Forgetting this shows up asRenderer 'undefined' is not importedor a silently blank chart. - Dev-only warnings ship in a
developmentexport-condition build — Vite, webpack, Rspack, Next.js and Vitest resolve it in dev; esbuild, Bun and default Parcel get the production build (no warnings) unless thedevelopmentcondition is added. Neither build needs aprocessglobal - Legacy
/coreimports are gone in v3 — usefrom 'react-use-echarts'; the oldreact-use-echarts/corealias was removed. optionis reference-reactive — a new reference auto-triggerssetOption; in-place mutation is not observedsetOptionOpts,initOptsand custom theme objects areJSON.stringify-keyed — value-equal inline objects (including nestedreplaceMergearrays) count as unchanged; serialization is not canonical, so property order affects the key. A changedsetOptionOptsre-appliesoption; a changedinitOptsor theme recreates the instance. Memoize to avoid repeated serialization, and never mutate in place- Imperative
setOption/clear/appendDatalast until the next real prop change — unrelated re-renders keep them; a newoptionreference or changedsetOptionOptsvalue re-applies the declarative option - Only
"macarons"needs registration —"light"/"dark"are ECharts 6's own themes ("light"= ECharts"default"); callregisterBuiltinThemes()from'react-use-echarts/themes/registry'once before using"macarons" onEventssupports two forms — shorthand(params) => voidor full{ handler, query?, context? }; inline objects/handlers are fine — proxies call the latest handler; only event-name,query(shallow) orcontextchanges rebind. ECharts holds the proxy, soinstance.off(name, handler)cannot remove these listeners — drop the key fromonEventsinstead- Chart linkage — same
groupstring syncs tooltips/highlights across charts - Lazy init is a one-shot latch —
lazyInit/useLazyInitforward onlyroot,rootMarginandthresholdto theIntersectionObserver(scrollMarginis ignored); once visible, the chart stays initialized, and turninglazyIniton after an eager init keeps the chart. Invalid observer settings log viaconsole.error(notonError) and fall back to eager init onErrorrouting — receives handled effect-operation and imperative API failures; without it, effect failures log viaconsole.errorand imperative methods rethrow.off()errors during dynamic event rebinding surface directly
For usage examples and full API details, see README.md in this package.