echarts-for-react: Guide to React Apache ECharts Setup · Examples · Events

A practical, no-fluff technical guide to using echarts-for-react (React wrapper for Apache ECharts) — installation, examples, events, customization, and SEO-friendly tips for building interactive React charts.

1. Quick SERP analysis & user intent

Top results for queries like „echarts-for-react”, „React ECharts”, and „echarts-for-react tutorial” are dominated by: the official Apache ECharts docs, the echarts-for-react GitHub repo / npm page, medium/dev.to tutorials, LogRocket/StackOverflow examples, and CodeSandbox demos. Expect the search landscape to favor practical how-tos and copy-paste examples over abstract marketing pages.

User intents across the top-10 are primarily informational and transactional (how to install, how to implement). Secondary intents include comparative (library vs library) and developer troubleshooting (errors, events, TypeScript tips). Commercial intent (choosing a chart library) appears when queries compare alternatives like Chart.js, Recharts, or React-Vis.

Competitors typically cover setup and a few examples (line/bar/pie), but most stop short of deep event handling, performance tips, and dashboard composition. That gap is where this guide positions itself: concise start-to-finish steps with hooks, events, resize handling, and small pragmatic patterns for production apps.

2. Semantic core (expanded) — clusters and keywords

Using your seed keywords, I’ve expanded a high-value semantic core (medium/high frequency and intent-driven queries). These are grouped by topical cluster so you can sprinkle them into headings, code comments, and anchor text without keyword-stuffing.

Core / Primary

• echarts-for-react (link: GitHub)
• React ECharts
• React Apache ECharts
• echarts-for-react tutorial
• echarts-for-react installation

Usage / Intent-driven (setup & examples)

• echarts-for-react example
• echarts-for-react setup
• echarts-for-react getting started
• React chart component
• React data visualization

Advanced / Customization / Events

• echarts-for-react customization
• echarts-for-react events
• React interactive charts
• echarts setOption
• echarts-for-react typescript

Related / LSI

• Apache ECharts
• echarts instance, ref, init, dispose
• tooltip formatter
• responsive charts, resize, ResizeObserver
• visualMap, toolbox, grid, xAxis, yAxis

Use these clusters to compose title tags, H2/H3s, alt texts, and internal anchors. Keep phrases natural: prefer „echarts-for-react example” inside a sentence rather than repeating the token as-is in every other line.

3. Top user questions (PAA + forums) — shortlist

Collected from People Also Ask patterns, Q&A forums, and tutorial titles. These are the most frequently searched developer queries around this stack:

• How do I use echarts in React?
• How to install echarts-for-react?
• How to handle events (click/hover) with echarts-for-react?
• How to customize tooltips and legends?
• How to make echarts responsive in React?
• How to use echarts-for-react with TypeScript?
• How to update data (setOption) without remounting?

From these, the three most relevant for a concise FAQ are: installation/getting started, events handling, and customization/responsiveness — see the FAQ at the bottom.

4. Getting started: installation and minimal example

Install the two packages: the core Apache ECharts engine and the React wrapper. This split is intentional: ECharts stays engine-agnostic and the wrapper merely manages lifecycle and mounting in React.

Install with npm or yarn. The command is short, so run it and stop pretending you’ll do it later:

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

Then, create a simple functional component. The example below shows a standard pattern: define an options object, pass it to the wrapper, and let React do its job. For dynamic updates use state and pass the updated option object — prefer minimal mutated changes to keep performance predictable.

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

const option = {
  title: { text: 'Sales' },
  tooltip: {},
  xAxis: { data: ['Mon','Tue','Wed','Thu','Fri'] },
  yAxis: {},
  series: [{ type: 'bar', data: [5, 20, 36, 10, 10] }]
};

export default function SimpleChart() {
  return <ReactECharts option={option} style={{height: '350px'}} />;
}

5. Events, refs and lifecycle: building interactive charts

Interactivity is where echarts-for-react shines: you can use the onEvents prop to map ECharts events (click, legendselectchanged, datazoom) to handlers. This is convenient for simple cases and keeps your code declarative.

For more control — programmatic calls, manual resize, or instance-level registration — access the echarts instance through a ref. The wrapper exposes getEchartsInstance(), so you can call setOption, on, off, or resize directly.

Example: combine onEvents for simple clicks and a ref when you need to call resize() on window changes or animate programmatic highlights.

import React, { useRef, useEffect } from 'react';
import ReactECharts from 'echarts-for-react';

export default function InteractiveChart() {
  const echRef = useRef(null);

  const onEvents = {
    click: (params) => console.log('clicked', params)
  };

  useEffect(() => {
    const instance = echRef.current?.getEchartsInstance();
    if (!instance) return;
    const onResize = () => instance.resize();
    window.addEventListener('resize', onResize);
    return () => window.removeEventListener('resize', onResize);
  }, []);

  return <ReactECharts ref={echRef} option={{/* ... */}} onEvents={onEvents} />;
}

6. Customization, performance and dashboard tips

Customization is mainly about the ECharts option object: tooltip.formatter, legend, visualMap, series styles, and rich text. Treat options as declarative; mutate them through state or use setOption with notMerge/replaceMerge flags for performance-sensitive updates.

Performance tips: for very large datasets use progressive rendering, sampling, or WebGL (the ECharts GL extension). Avoid remounting charts — prefer setOption for incremental updates. If you must reinitialize, call dispose() on the instance first to avoid memory leaks.

When composing dashboards, keep charts isolated in container components, memoize options with React.useMemo, and centralize resize logic. Use a ResizeObserver on chart containers to call instance.resize() instead of relying only on window.resize.

7. Common pitfalls & troubleshooting

Missing the echarts package: echarts-for-react is just a wrapper. If you see „echarts is not defined” or blank charts, check that both packages are installed and the versions are compatible. Use consistent major versions to avoid breaking API changes.

TypeScript users: install type definitions if needed, or declare types for the wrapper. The community provides type hints, but sometimes you need to assert any for the echarts instance. Prefer explicit typing for options to get editor autocomplete for series, axis, and tooltip props.

SSR issues: ECharts manipulates the DOM and window, so avoid rendering charts on the server. Lazy-load the chart component or guard it with a client-side-only condition to prevent SSR errors in Next.js or similar frameworks.

8. Examples roundup (useful snippets)

Here are a few short snippets and patterns you will actually use in production: responsive resize, setOption updates, and event mapping. Keep them as utility hooks or small HOC wrappers to reuse across dashboards.

• Responsive: call instance.resize() from ResizeObserver.
• Update data: use setOption(newOption, { notMerge: false }) for incremental changes.
• Events: prefer onEvents for mapping, but use instance.on for advanced use-cases.

9. Sources, links & useful resources

Canonical and authoritative sources you should bookmark now (or later, like everyone):

• Apache ECharts docs — the definitive reference for options and features.
• echarts-for-react GitHub — wrapper source, issues and PRs.
• echarts-for-react on npm — package and versions.
• Dev.to tutorial — a pragmatic walkthrough with interactive demos.

FAQ

How do I install and get started with echarts-for-react?

Install both packages: npm i echarts echarts-for-react. Import the wrapper import ReactECharts from 'echarts-for-react', create an options object, and render <ReactECharts option={option} />. For dynamic changes use React state and update the option or access instance methods via a ref.

How can I handle chart events in echarts-for-react?

Use the onEvents prop to map event names to handlers (e.g., {'{ click: handleClick }'}). For advanced control, get the echarts instance via a ref (ref.current.getEchartsInstance()) and call instance.on('click', handler) or instance.off. This gives you both declarative and imperative options.

How do I customize and make charts responsive in echarts-for-react?

Customize via the options object (tooltip, legend, visualMap). For responsiveness, size the container with CSS, and call instance.resize() when the container changes. Prefer ResizeObserver or the wrapper’s autoResize (if available) rather than only window.resize for reliable behavior in flexible layouts.

Core:
- echarts-for-react
- React ECharts
- React Apache ECharts
- echarts-for-react tutorial
- echarts-for-react installation
Usage:
- echarts-for-react example
- echarts-for-react setup
- echarts-for-react getting started
- React chart component
- React data visualization
Advanced:
- echarts-for-react customization
- echarts-for-react events
- React interactive charts
- echarts setOption
- echarts-for-react typescript
LSI / related:
- Apache ECharts
- echarts instance
- getEchartsInstance
- setOption
- dispose
- tooltip formatter
- visualMap
- ResizeObserver
- responsive charts
- webgl echarts
Misc:
- echarts-for-react github
- echarts-for-react npm
- echarts examples
- echarts dashboard
- echarts hooks