Markdown source (editable)

# echarts-for-react: practical guide to React + Apache ECharts

Quick setup, examples, events and customization for interactive React charts (echarts-for-react | React ECharts).

## Why choose echarts-for-react?

echarts-for-react wraps Apache ECharts into a small, idiomatic React component. You get:
- High-performance plotting for large datasets.
- Rich built-in chart types and interactions.
- Direct access to ECharts options and APIs.

If you want a React chart library that gives you both declarative components and low-level control, this combo is a winner.

## Getting started: installation and basic setup

1. Install packages:
\`\`\`bash
npm install echarts-for-react echarts --save
# or
yarn add echarts-for-react echarts
\`\`\`

2. Minimal React component:
\`\`\`jsx
import React from 'react';
import ReactECharts from 'echarts-for-react';

export default function SimpleChart(){
  const option = {
    xAxis: { type: 'category', data: ['Mon','Tue','Wed','Thu','Fri'] },
    yAxis: { type: 'value' },
    series: [{ data: [820, 932, 901, 934, 1290], type: 'line' }]
  };
  return ;
}
\`\`\`

3. Tips: lazy import \`echarts\` when you need large charts to reduce bundle size.

## Events and interactivity

Attach event handlers with the \`onEvents\` prop. Example:
\`\`\`jsx
const onEvents = {
  click: (params, instance) => {
    console.log('clicked', params);
  }
};

\`\`\`

This gives you rich interactivity for dashboards and drilldowns.

## Customization and advanced usage

- Use \`getInstance\` or refs to call \`setOption\` for live updates.
- Combine with React state for dynamic data.
- Configure themes or register custom charts via ECharts API.

## Best practices

- Keep \`option\` objects stable (memoize them) to avoid unnecessary rerenders.
- Use \`notMerge\` and \`lazyUpdate\` flags when calling \`setOption\`.
- Consider code-splitting if you use multiple heavy chart types.

---

### FAQ

**How do I install echarts-for-react?**  
Install via npm or yarn: \`npm install echarts-for-react echarts\`.

**How to handle chart events in echarts-for-react?**  
Use the \`onEvents\` prop mapping ECharts events to handlers.

**Can I customize and animate charts?**  
Yes — provide full \`option\` objects, use ECharts animation and the \`setOption\` API.

Why choose echarts-for-react?

echarts-for-react is a thin React wrapper around Apache ECharts that gives you the best of both worlds: a React-friendly component model and direct access to ECharts’ powerful options and runtime API. It’s not trying to be a “React-only” chart library that hides the underlying engine; instead it exposes ECharts cleanly so you can use every capability—maps, heatmaps, candlesticks, or custom graphics—without fighting the API.

For teams that need performance and flexibility, React data visualization with ECharts is compelling. Large datasets render smoothly thanks to ECharts’ optimized canvas rendering, and the wrapper keeps integration straightforward. If you’re building dashboards, interactive reports, or embedding charts that require custom event handling, echarts-for-react makes that process direct and predictable.

Bottom line: choose echarts-for-react when you want a React chart component that doesn’t strip away the engine’s power. Expect a short learning curve—if you already know ECharts options, you’ll be productive fast.

Getting started: installation and basic setup

Installation is intentionally boring: use npm or yarn. The two packages you need are the React wrapper and the ECharts engine. This setup keeps your dependency graph explicit and lets you upgrade ECharts independently of the wrapper.

npm install echarts-for-react echarts --save
# or
yarn add echarts-for-react echarts

A minimal React component looks like this and will get you a working line chart in a few minutes. Note how the wrapper accepts an ECharts “option” object—this is where you describe axes, series, tooltips, and more.

import React from 'react';
import ReactECharts from 'echarts-for-react';

export default function SimpleChart(){
  const option = {
    xAxis: { type: 'category', data: ['Mon','Tue','Wed','Thu','Fri'] },
    yAxis: { type: 'value' },
    series: [{ data: [820, 932, 901, 934, 1290], type: 'line' }]
  };
  return <ReactECharts option={option} style={{height: '320px'}}/>;
}

Pro tip: memoize option objects with useMemo to avoid needless updates. Also, if bundle size matters, consider dynamic import of heavy chart types or ECharts modules only when needed.

Events and interactivity

One of the nice things about React ECharts is that it exposes a straightforward way to attach event handlers: pass an onEvents object mapping event names to functions. You can handle clicks, mouseovers, legend toggles, and even custom events emitted by extensions.

Example: map ‘click’ to a function that receives params and the ECharts instance. With that you can read which series and datapoint were clicked and respond—open a modal, fetch detail data, or update another chart.

const onEvents = {
  click: (params, instance) => {
    console.log('clicked', params);
  }
};
<ReactECharts option={option} onEvents={onEvents}/>

For dashboard-style interactivity, combine event handlers with React state and refs: update other components on click, or call instance.setOption for animated transitions. This keeps the UI responsive and the data flow clear.

Customization, state updates and advanced usage

echarts-for-react doesn’t get in the way when you need to customize styling, register themes, or add custom series. Feed any valid ECharts option object to the component. For runtime updates, access the chart instance via a ref or use the provided helper methods (getInstance) to call setOption with precise control.

Mind the parameters: setOption accepts flags like notMerge and lazyUpdate that let you control merging behavior and performance. When animating frequent real-time updates, use incremental rendering options available in ECharts for very large datasets.

You can also register custom components or series on the ECharts side and still render via echarts-for-react. This is useful when embedding bespoke visualizations in a React dashboard without sacrificing React’s composition model.

Best practices for production React ECharts

Keep your option objects stable by memoizing them with React’s useMemo. Unstable option props trigger rerenders and can lead to flicker or performance loss. Also, prefer smaller, focused option objects rather than massive single objects if you dynamically update portions of the chart.

• Memoize options (useMemo) and handlers (useCallback).
• Lazy-load heavy chart components and ECharts modules.
• Use refs/getInstance for controlled updates via setOption.

Additionally, test interactions on mobile and ensure touch events are handled correctly. ECharts provides sensible defaults, but complex dashboards still need careful tuning of tooltip triggers, axis formatting, and responsive sizing.

Short example: real-time update pattern

When streaming data, append new points and call setOption with notMerge: false to animate updates. Use requestAnimationFrame or throttling to avoid overwhelming the UI. The pattern below demonstrates pushing a new datapoint every tick while preserving the existing series array.

const chartRef = useRef();

useEffect(() => {
  const id = setInterval(() => {
    const instance = chartRef.current.getEchartsInstance();
    instance.setOption({
      series: [{ data: nextDataArray }]
    }, false, false); // notMerge, lazyUpdate
  }, 1000);
  return () => clearInterval(id);
}, []);

This balances smooth animation with controlled updates; adjust the interval and throttling strategy to match your data velocity.

Conclusion

echarts-for-react is a pragmatic choice for teams needing full access to Apache ECharts inside React. It gives you declarative components and low-level control, making it suitable for dashboards, reporting, and interactive visualizations.

Learn the ECharts option model first, then wrap it in React-friendly patterns (memoization, refs, and event handlers). With those practices, you’ll avoid common pitfalls and deliver snappy, feature-rich charts.

If you want a next step: try converting one existing chart to echarts-for-react, add an event-based drilldown, and measure bundle size before and after applying lazy imports.

Quick external references (backlinks)

Official wrapper: echarts-for-react ·
Engine docs: React Apache ECharts ·
Tutorial: echarts-for-react tutorial

FAQ

How do I install echarts-for-react?

Install via npm or yarn: npm install echarts-for-react echarts –save. Import the wrapper and pass an ECharts option object.

How to handle chart events in echarts-for-react?

Provide an onEvents prop mapping ECharts event names (e.g., “click”) to handler functions. Handlers receive (params, instance) so you can read data and control the chart.

Can I customize and animate charts created with React ECharts?

Yes. Use full ECharts options, setOption for runtime updates, and ECharts’ animation config. For advanced customization, register custom series or themes on the ECharts instance.

Semantic core (expanded keyword clusters)

Search intent & competitor analysis summary

Analyzing typical English-language SERP for these keywords shows dominant user intents:

• Informational: tutorials, getting started, examples, API usage.
• Transactional/Navigational: GitHub repo, npm package pages, official docs.
• Commercial/Comparative: “best React chart library” queries appear as comparisons.

Top pages usually combine a quick code sample (featured-snippet friendly), a short installation section, event handling examples, and small dashboard use-cases. To compete, your article must include succinct install + sample code (for featured snippets), clear event examples, and best-practice tips.