Quick summary

echarts-for-react is the most straightforward React wrapper around Apache ECharts (formerly Baidu ECharts). It preserves the full power of ECharts (rich chart types, themes, responsive rendering, and advanced events) while exposing a React-friendly component API. If you need highly interactive charts, cross-plot coordination, or custom rendering hooks inside React, this library is a great candidate.

This guide covers installation, setup, core examples, customization patterns (including event handling), and best practices to keep rendering fast. Links to official sources and a compact FAQ are included. For a hands-on tutorial reference, see the developer write-up: echarts-for-react tutorial on dev.to.

Top-10 SERP analysis & user intent (summary)

I analyzed the typical English-language top-10 results for queries such as „echarts-for-react”, „React ECharts”, and „echarts-for-react tutorial”. Results usually include:

• GitHub repo and README (e.g., hustcc/echarts-for-react) — installation, API, examples.
• Apache ECharts docs (official) — chart options and concepts.
• npm package page — install instructions and versions.
• Tutorial blog posts (dev.to, Medium, personal blogs) — step-by-step examples and use cases.
• Example code sandboxes and GitHub projects — dashboards and live samples.

Detected user intents by query cluster:

Competitor coverage and depth:

• GitHub / README: medium-depth API + quick examples — high trust but low tutorial polish.
• Official ECharts docs: deep coverage of options and chart types — not React-specific.
• Tutorial posts: step-by-step with examples and code sandboxes — great for beginners.
• StackOverflow / Q&A: specific issues (SSR, resize, event propagation) — problem-focused.

Expanded semantic core (clusters + LSI)

Below is an intent-driven semantic keyword structure you can use for on-page SEO and internal linking. Use these phrases naturally in headings, captions, alt text, and anchor text.

Primary (head terms)
- echarts-for-react
- React ECharts
- React Apache ECharts
- echarts-for-react tutorial
- echarts-for-react installation
- echarts-for-react getting started
Installation & Setup
- echarts-for-react setup
- install echarts-for-react npm
- yarn add echarts echarts-for-react
- typescript echarts-for-react
Examples & Usage
- echarts-for-react example
- React interactive charts
- React chart component
- react echarts example code
- using echarts in React
Customization & Events
- echarts-for-react customization
- echarts-for-react events
- echarts setOption in React
- chart tooltip customize echarts
- theme echarts-for-react
Dashboard & Integration
- React ECharts dashboard
- realtime charts React echarts
- react data visualization with echarts
- echarts-for-react performance
Related / Alternatives (LSI)
- Apache ECharts
- echarts options object
- compare Recharts vs ECharts
- react-chartjs-2 vs echarts
- interactive data visualization React

Getting started & installation

Install the wrapper + upstream ECharts package. The wrapper delegates all rendering and options to Apache ECharts, so you need both. Typical command (npm):

npm install echarts echarts-for-react

If you use yarn: yarn add echarts echarts-for-react . For TypeScript projects, install typings if needed and import proper types from the ECharts package. The npm page contains version notes; check echarts-for-react installation on npm for the latest.

Minimal usage pattern — mount a component, pass an option object, and optionally handle events or set refs for direct ECharts API calls.

import React from 'react';
import ReactECharts from 'echarts-for-react';
const option = { xAxis:{}, yAxis:{}, series:[{ type:'line', data:[1,2,3] }] };
export default function MyChart(){ return ; }

Examples & interactive charts

echarts-for-react supports all ECharts chart types: line, bar, pie, scatter, candlestick, map, sankey, heatmap, radar, and custom series. Interactivity (zoom, brush, tooltip, legend selection) is available via options and built-in components.

To make charts interactive from React, use controlled pattern: keep chart data/options in state, update the object reference on change, and let ECharts re-render. For very frequent updates (e.g., real-time), use the ECharts instance API via a ref to avoid expensive full re-renders.

Example: toggling series visibility programmatically or connecting chart events to React state. Use onEvents prop to bind ECharts DOM events and dispatch React handlers.

Customization, events and advanced API

echarts-for-react exposes these important props: option (ECharts option object), style/className, notMerge (controls setOption merging), lazyUpdate, and onEvents (object mapping event names to handlers). You can also get the ECharts instance via ref for granular control:

const ref = useRef();
<ReactECharts ref={ref} option={option} />
// then: ref.current.getEchartsInstance().dispatchAction(...)

Use getEchartsInstance() for performance-sensitive tasks: dispatchAction, resize, or convertToPixel / convertFromPixel calls. When customizing tooltips, labels, or rendering custom series, author formatter callbacks or use renderItem in ECharts’ custom series API.

Event handling: common events include ‚click’, ‚legendselectchanged’, ‚datazoom’, ‚brushselected’. Bind them via onEvents={{ click: handleClick }} or attach programmatically to the instance if you need one-off handlers.

Performance and best practices

Large datasets or many series can hurt performance. Strategies to keep React + ECharts responsive:

• Use the ECharts instance API (via ref) to update only what’s necessary (dispatchAction, setOption with partial options and notMerge true).
• Throttle/debounce updates from high-frequency sources (websockets, fast timers).
• Prefer downsampling or progressive rendering for very many points.

Also, avoid recreating option objects every render. Memoize options with useMemo and update only the parts that change. For SSR, ECharts does not naturally render charts on the server; render placeholders or hydrate client-side only.

Finally, use themes and lazy loading if you have many chart types; this reduces the initial bundle size when importing optional ECharts extensions (maps, GL, or custom renderers).

Integrating echarts-for-react into dashboards

Dashboards require layout, resize handling, and coordinated interaction between charts. Keep a central state (Redux, Zustand, or Context) for cross-filtering and use chart events to update that state. When a chart triggers a brush or click, dispatch a state change and let connected charts update their options.

For responsive behavior, call the instance resize() on container size change or use the library’s auto-resize. If you use CSS grid or flex, ensure the chart container has height — ECharts needs dimensions at render time.

Example integration points: exporting images with getDataURL, exporting CSV from series data, or linking to drill-down routes on click events. These are facilitated by having access to the ECharts instance via ref.

Troubleshooting common issues

Problem: Charts render blank or with wrong size. Solution: Check container height, call resize() after layout changes, and ensure options are valid.

Problem: Events not firing. Solution: Confirm events are attached via onEvents or instance.on; some events are bound to components (e.g., legendselectchanged).

Problem: TypeScript complaints. Solution: Import types from echarts and augment the wrapper types, or create a small d.ts shim until upstream provides stronger typings.

Authoritative references & backlinks

Use these official sources as backlinks from your article (anchor text chosen for SEO):

• echarts-for-react — official GitHub repo and README (installation, props, examples).
• React ECharts (Apache ECharts official docs) — chart options, examples, API.
• echarts-for-react installation on npm — package page and version info.
• echarts-for-react tutorial — practical tutorial and examples.

FAQ

1. How do I install echarts-for-react and get a basic chart running?

Install both packages: npm install echarts echarts-for-react . Import the wrapper and provide an ECharts option object as the option prop. Example: <ReactECharts option={option} /> .

2. How can I handle chart click events in React?

Use the onEvents prop: onEvents={{ click: (params) => handleClick(params) }} . For advanced control, get the ECharts instance via ref and use instance.on('click', handler) .

3. What are the best practices for performance with many data points?

Memoize option objects, use the ECharts instance API for partial updates, apply downsampling or progressive rendering, and throttle high-frequency updates.