{"id":10776,"library":"echarts-for-react","title":"React Wrapper for Apache ECharts","description":"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.","status":"active","version":"3.0.6","language":"javascript","source_language":"en","source_url":"https://github.com/hustcc/echarts-for-react","tags":["javascript","react","component","echarts-react","echarts","react-echarts","chart","charts","graph","typescript"],"install":[{"cmd":"npm install echarts-for-react","lang":"bash","label":"npm"},{"cmd":"yarn add echarts-for-react","lang":"bash","label":"yarn"},{"cmd":"pnpm add echarts-for-react","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for rendering React components.","package":"react","optional":false},{"reason":"Core charting library that this component wraps; must be installed separately.","package":"echarts","optional":false}],"imports":[{"note":"This is the primary component for general use. For optimal bundle size, consider `ReactEChartsCore`.","wrong":"const ReactECharts = require('echarts-for-react');","symbol":"ReactECharts","correct":"import ReactECharts from 'echarts-for-react';"},{"note":"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])`).","wrong":"import { ReactEChartsCore } from 'echarts-for-react/lib/core';","symbol":"ReactEChartsCore","correct":"import ReactEChartsCore from 'echarts-for-react/lib/core';"},{"note":"TypeScript type definition for ECharts chart options, essential for type-safe configuration.","symbol":"EChartsOption","correct":"import type { EChartsOption } from 'echarts-for-react';"}],"quickstart":{"code":"import React, { useState, useEffect, useRef } from 'react';\nimport ReactECharts from 'echarts-for-react'; // Or use 'echarts-for-react/lib/core' with manual imports\nimport * as echarts from 'echarts/core';\nimport { BarChart } from 'echarts/charts';\nimport { GridComponent, TooltipComponent, TitleComponent, DatasetComponent } from 'echarts/components';\nimport { CanvasRenderer } from 'echarts/renderers';\n\n// Register necessary ECharts components if using ReactEChartsCore\n// For ReactECharts (default import), these are often included, but explicit registration is good practice\necharts.use([\n  BarChart,\n  GridComponent,\n  TooltipComponent,\n  TitleComponent,\n  DatasetComponent,\n  CanvasRenderer\n]);\n\nconst EChartsDemo: React.FC = () => {\n  const chartRef = useRef<echarts.ECharts | null>(null);\n\n  const getOption = () => {\n    return {\n      title: {\n        text: 'ECharts Sample Bar Chart'\n      },\n      tooltip: {},\n      xAxis: {\n        type: 'category',\n        data: ['Category A', 'Category B', 'Category C', 'Category D', 'Category E']\n      },\n      yAxis: {\n        type: 'value'\n      },\n      series: [{\n        name: 'Sales',\n        data: [120, 200, 150, 80, 70],\n        type: 'bar'\n      }]\n    };\n  };\n\n  const onChartReady = (instance: echarts.ECharts) => {\n    console.log('ECharts instance is ready:', instance);\n    chartRef.current = instance;\n  };\n\n  const onEvents = {\n    'click': (params: any) => {\n      console.log('Chart clicked:', params.name);\n    },\n    'mouseover': (params: any) => {\n      // console.log('Mouse over:', params.seriesName);\n    }\n  };\n\n  useEffect(() => {\n    // Example: Manual resize after a delay (e.g., if container size changes dynamically)\n    const timer = setTimeout(() => {\n      chartRef.current?.resize();\n      console.log('ECharts instance manually resized.');\n    }, 2000);\n    return () => clearTimeout(timer);\n  }, []);\n\n  return (\n    <div style={{ width: '100%', height: '400px', border: '1px solid #ccc', padding: '10px' }}>\n      <h3>Your ECharts Visualization</h3>\n      <ReactECharts\n        option={getOption()}\n        notMerge={true}\n        lazyUpdate={true}\n        theme=\"light\"\n        onChartReady={onChartReady}\n        onEvents={onEvents}\n        opts={{ renderer: 'canvas' }} // Recommend specifying renderer explicitly\n        style={{ height: '100%' }}\n      />\n    </div>\n  );\n};\n\nexport default EChartsDemo;\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"The 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.","severity":"breaking","affected_versions":">=3.0.0"},{"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([...])`.","message":"Large 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure `echarts` is installed in your project: `npm install echarts` or `yarn add echarts`.","message":"`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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"ECharts 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Install `echarts` in your project: `npm install echarts` or `yarn add echarts`. Verify that it's correctly listed in your `package.json`.","cause":"The `echarts` peer dependency is missing or not accessible at runtime.","error":"Error: ECharts is not initialized"},{"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.","cause":"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.","error":"TypeScript error: Property 'option' does not exist on type 'IntrinsicAttributes & ReactEChartsProps'."},{"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, ...])`.","cause":"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()`.","error":"Error: Component 'grid' not found."}],"ecosystem":"npm"}