ECharts for React: Interactive Charts, Setup & Examples

Short summary: This guide shows how to install and set up echarts-for-react, build interactive React ECharts, handle events, customize charts for dashboards, and optimize rendering for production. Code samples and integration patterns are included for fast implementation.

Quick start — Installation and first chart

To get a working React chart in minutes, install the wrapper and core library. The recommended packages are echarts-for-react (React component wrapper) and echarts (Apache ECharts engine). This combination gives you declarative React props and the full power of ECharts options for visuals, interactions, and theming.

Install via npm or yarn. This is the canonical echarts-for-react installation step you’ll use in most projects:

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

Then, mount a basic chart component inside your React app. The example below shows a simple line chart using the core option object that ECharts understands:

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

export default function SimpleLine() {
  const option = {
    xAxis: { type: 'category', data: ['Mon','Tue','Wed','Thu','Fri','Sat','Sun'] },
    yAxis: { type: 'value' },
    series: [{ data: [120,200,150,80,70,110,130], type: 'line' }]
  };
  return <ReactECharts option={option} style={{height: '360px'}} />;
}

This is the shortest path from zero to a rendered React chart component. For a worked tutorial and variants, see this echarts-for-react tutorial.

Building interactive charts and handling events

Interaction is where React ECharts shines: you attach event handlers to the component and react to user actions (click, mouseover, legendselectchanged, datazoom, etc.). Use the onEvents prop or the component ref for imperative control. This is essential for dashboards where clicks drive filters or drilldowns.

Example using onEvents to handle clicks and update state. This keeps the logic declarative and React-friendly.

const onEvents = {
  click: (params) => {
    // params contains seriesIndex, dataIndex, name, value
    console.log('Clicked point', params);
    // e.g., setState to show details panel or fetch drilldown data
  }
};

<ReactECharts option={option} onEvents={onEvents} />

When you need fine-grained control such as programmatic resizing or calling ECharts methods, get the instance via ref. The wrapper exposes getEchartsInstance(). Use refs for exporting images, dynamic data updates without remounts, and advanced event lifecycles.

Tip: For voice search and snippets, answer short questions concretely. For example, “How do I capture a click on a bar in echarts-for-react?” Answer: add an onEvents click handler, read params.seriesIndex and params.dataIndex, then update state or route accordingly.

Customization, theming, and dashboard patterns

Customization starts with the ECharts option object: tooltip formatters, axis label formatters, custom colors, gradients, markPoints, and annotations. Combine these with React props to make reusable chart components for dashboards—think of a Chart wrapper that accepts type, data, and optionsOverrides.

You can apply themes globally or per-chart. To use a built-in or custom theme, import it or register it with ECharts, then pass the theme name to the wrapper via the theme prop. Themes are useful to maintain brand consistency across multiple charts and preserve accessibility (contrast, font sizes).

When building dashboards, follow a few pragmatic patterns:

• Create small presentational chart components that accept plain data and produce an option.
• Keep data transformation outside the chart component (selectors, memoized transforms) to avoid re-renders.
• Use the chart ref for bulk operations (resize on layout change, export, sync zoom across charts).

These patterns help you scale from a single React ECharts dashboard to dozens of panels without brittle coupling.

Performance and best practices

Large series and frequent updates are where ECharts can be taxed. Avoid recreating the option object each render—memoize it (React.useMemo) and only rebuild when the underlying data changes. Pass immutable data shapes so shallow comparison patterns detect real changes.

For high-volume real-time streams, consider:

• downsampling or summarizing on the server
• using progressive rendering via ECharts’ progressive options
• throttling updates and batching multiple updates into one option merge

This preserves interactivity while keeping frame rates smooth.

Also use virtualization for dashboards that render many charts at once (render only visible panels) and prefer canvas-based series (the default) over SVG for heavy plotting. Keep event handlers lightweight and move heavy logic to web workers when possible.

Integration patterns: TypeScript, hooks, SSR considerations

TypeScript provides safer props and option typing. The ECharts option shape is big; in practice, type your component props (data, config) and treat the generated option as any or a narrow subset. Many teams expose a small domain API for charts and map it to ECharts options internally, which simplifies type definitions.

If you use hooks, a concise pattern is a custom hook that returns an option and handlers: useChartOption(data, config). This isolates transformation logic and can be unit-tested separately from rendering concerns. For example, memoize heavy computations with useMemo and event callbacks with useCallback.

Server-side rendering (SSR) usually only needs the static layout and a placeholder; ECharts requires a browser environment for actual rendering. Use hydration: render a lightweight skeleton server-side and mount the chart client-side. Avoid calling getEchartsInstance() during SSR lifecycle—guard it behind useEffect or checks for window/document.

Checklist before you ship

Before deploying a React app with ECharts, verify the following:

• Bundle size: import only needed modules from echarts (use ECharts modular builds if size matters).
• Accessibility: ensure tooltips and legends are keyboard-navigable or provide alternative summaries.
• Responsive behavior: handle resize events and test on mobile; use style or parent container sizes explicitly.

Also include tests for chart rendering where possible—snapshot the generated option object and assert expected keys/values rather than relying on DOM snapshots alone. That keeps your UI tests stable even when theme CSS shifts slightly.

---

Selected links and resources

Further reading and resources (backlinks):

• echarts-for-react tutorial — practical walkthrough and examples.
• Apache ECharts — official docs for options, themes, and examples.
• echarts-for-react GitHub — source, issues, and advanced usage.
• echarts-for-react installation and npm package — package details and versions.

Pro tip: If you need to sync tooltips or zoom across multiple charts, use the group API in ECharts: assign the same group id to instances and call echarts.connect(). This makes cross-chart interactions feel native.

---

FAQ

---

Semantic core (expanded keywords & clusters)

Popular user questions (collected)

Other near-top questions users ask:

• How to export an ECharts chart as PNG in React?
• How to sync zoom and tooltip across multiple charts?
• Can I use ECharts with TypeScript in React?
• How to apply custom themes to echarts-for-react?
• What is the best way to update chart data without re-rendering?
• How to use ECharts map / geo features in React?
• How to lazy-load large charts to reduce initial bundle size?

If you want, I can generate ready-to-publish code components (TypeScript + hooks), or a stripped-down starter repo that implements the dashboard patterns above.