Registry / web-framework / echarts-for-react

echarts-for-react

JSON →
library3.0.6jsnpmunverified

echarts-for-react is a robust and widely-used React component that seamlessly integrates Apache ECharts, a powerful charting library, into React applications. It provides a declarative way to render various types of charts and visualizations, abstracting away direct ECharts instance management. The current stable version is 3.0.6. The project maintains an active development pace with frequent minor updates and bug fixes, building upon the significant v3.0.0 release that introduced ECharts v5 support and a full TypeScript rewrite. Key differentiators include its simplicity, direct exposure of ECharts options as React props, comprehensive TypeScript support, and the ability to manually import ECharts modules for bundle size optimization, making it a preferred choice for React developers needing advanced data visualization.

npm install echarts-for-react
INSTALL
IMPORT
SIG · ECHARTS-FOR-REACT
E
echarts-for-react
web-frameworkjavascriptv3.0.6
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

ReactECharts
✓ import ReactECharts from 'echarts-for-react';
✗ const ReactECharts = require('echarts-for-react');
This is the primary component for general use. For optimal bundle size, consider `ReactEChartsCore`.
ReactEChartsCore
✓ import ReactEChartsCore from 'echarts-for-react/lib/core';
✗ import { ReactEChartsCore } from 'echarts-for-react/lib/core';
Use this component for manual ECharts module imports to reduce bundle size, especially with ECharts v5/v6. Requires separate imports and registration of ECharts charts, components, and renderers (e.g., `echarts.use([BarChart, GridComponent])`).
EChartsOption
✓ import type { EChartsOption } from 'echarts-for-react';
TypeScript type definition for ECharts chart options, essential for type-safe configuration.

This quickstart demonstrates a functional React component rendering a basic ECharts bar chart. It shows how to define chart options, handle chart readiness and events, and access the ECharts instance for manual operations like resizing. It also includes the necessary ECharts module imports and registration for best practice.

import React, { useState, useEffect, useRef } from 'react'; import ReactECharts from 'echarts-for-react'; // Or use 'echarts-for-react/lib/core' with manual imports import * as echarts from 'echarts/core'; import { BarChart } from 'echarts/charts'; import { GridComponent, TooltipComponent, TitleComponent, DatasetComponent } from 'echarts/components'; import { CanvasRenderer } from 'echarts/renderers'; // Register necessary ECharts components if using ReactEChartsCore // For ReactECharts (default import), these are often included, but explicit registration is good practice echarts.use([ BarChart, GridComponent, TooltipComponent, TitleComponent, DatasetComponent, CanvasRenderer ]); const EChartsDemo: React.FC = () => { const chartRef = useRef<echarts.ECharts | null>(null); const getOption = () => { return { title: { text: 'ECharts Sample Bar Chart' }, tooltip: {}, xAxis: { type: 'category', data: ['Category A', 'Category B', 'Category C', 'Category D', 'Category E'] }, yAxis: { type: 'value' }, series: [{ name: 'Sales', data: [120, 200, 150, 80, 70], type: 'bar' }] }; }; const onChartReady = (instance: echarts.ECharts) => { console.log('ECharts instance is ready:', instance); chartRef.current = instance; }; const onEvents = { 'click': (params: any) => { console.log('Chart clicked:', params.name); }, 'mouseover': (params: any) => { // console.log('Mouse over:', params.seriesName); } }; useEffect(() => { // Example: Manual resize after a delay (e.g., if container size changes dynamically) const timer = setTimeout(() => { chartRef.current?.resize(); console.log('ECharts instance manually resized.'); }, 2000); return () => clearTimeout(timer); }, []); return ( <div style={{ width: '100%', height: '400px', border: '1px solid #ccc', padding: '10px' }}> <h3>Your ECharts Visualization</h3> <ReactECharts option={getOption()} notMerge={true} lazyUpdate={true} theme="light" onChartReady={onChartReady} onEvents={onEvents} opts={{ renderer: 'canvas' }} // Recommend specifying renderer explicitly style={{ height: '100%' }} /> </div> ); }; export default EChartsDemo;
Debug
Known issues
breakingThe v3.0.0 release introduced a complete rewrite in TypeScript and explicit support for ECharts v5. Projects not using TypeScript may need refactoring due to changes in prop type validation and internal component structures. While generally backward compatible with ECharts v3 and v4, using older versions might not leverage all new features or bug fixes.
fix
Review your code for TypeScript compatibility. Ensure ECharts peer dependency is at least `^3.0.0`, with `^5.0.0` or `^6.0.0` recommended to align with modern ECharts features and `echarts-for-react` capabilities. Migrate to TypeScript if possible for better type safety.
affects: >=3.0.0
gotchaLarge bundle sizes can occur if the entire ECharts library is imported instead of only the necessary modules. This is a common issue when using the default `echarts-for-react` import without specific optimizations.
fix
Use `import ReactEChartsCore from 'echarts-for-react/lib/core';` and manually import only the required charts, components, and renderers from `echarts/charts`, `echarts/components`, and `echarts/renderers`. Then, register them using `echarts.use([...])`.
affects: >=1.0.0
gotcha`echarts-for-react` lists `echarts` as a peer dependency. This means `echarts` itself must be explicitly installed in your project, otherwise, the component will fail at runtime.
fix
Ensure `echarts` is installed in your project: `npm install echarts` or `yarn add echarts`.
affects: >=1.0.0
gotchaECharts instances do not always automatically resize when their containing HTML element changes dimensions. While `echarts-for-react` includes some resize detection, complex or dynamic layout changes may require manual intervention.
fix
Obtain the ECharts instance (e.g., via the `onChartReady` callback or a React `ref`) and call `instance.resize()` whenever the container's size changes. Consider using a `ResizeObserver` for robust detection of DOM element dimension changes.
affects: >=1.0.0
Errors
Common errors & fixes
Error: ECharts is not initialized
The `echarts` peer dependency is missing or not accessible at runtime.
fix
Install `echarts` in your project: `npm install echarts` or `yarn add echarts`. Verify that it's correctly listed in your `package.json`.
TypeScript error: Property 'option' does not exist on type 'IntrinsicAttributes & ReactEChartsProps'.
This typically indicates an outdated `echarts-for-react` version being used with newer ECharts options, or a conflict in TypeScript type definitions. It might also occur if a type from ECharts is not correctly imported.
fix
Ensure `echarts-for-react` is `v3.0.0` or higher, and `echarts` is also up-to-date (e.g., `^5.0.0` or `^6.0.0`). Check your `tsconfig.json` for correct module resolution and ensure `EChartsOption` type is imported if explicitly used.
Error: Component 'grid' not found.
When using `ReactEChartsCore` for bundle size optimization, not all necessary ECharts components (like `GridComponent`, `TooltipComponent`, or specific chart types) have been explicitly imported and registered with `echarts.use()`.
fix
Manually import all required ECharts components, charts, and renderers (e.g., `GridComponent`, `BarChart`, `CanvasRenderer`) from their respective `echarts/components`, `echarts/charts`, and `echarts/renderers` paths, then register them using `echarts.use([Component1, ChartType1, ...])`.
Upgrade
Version history
3.0.6latest on npm
Audit
Dependencies
reactrequiredPeer dependency required for rendering React components.
echartsrequiredCore charting library that this component wraps; must be installed separately.
Agent activity
12 hits · last 30 days
node
12
Resources
echarts-for-react — npm install echarts-for-react · libregistry