react-use-echarts

A powerful React hooks library for Apache ECharts, making it easy to use ECharts in your React applications with minimal boilerplate.

✨ Features

• 🎨 Easy to use - Simple and intuitive API with React Hooks
• 🚀 TypeScript support - Written in TypeScript with complete type definitions
• 📦 Lightweight - Zero dependencies except for React and ECharts
• 🛠 Flexible - Full access to ECharts instance and options
• ⚡ Auto-updating - Automatically updates chart when data or options change
• 📱 Responsive - Handles container resizing automatically

📦 Installation

1# Using npm
2npm install react-use-echarts echarts
3
4# Using yarn
5yarn add react-use-echarts echarts
6
7# Using pnpm
8pnpm add react-use-echarts echarts

🔨 Usage

1import { useEcharts, UseEchartsOptions } from 'react-use-echarts';
2
3function MyChart() {
4  const options: UseEchartsOptions['option'] = {
5    xAxis: {
6      type: 'category',
7      data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
8    },
9    yAxis: {
10      type: 'value'
11    },
12    series: [{
13      data: [820, 932, 901, 934, 1290, 1330, 1320],
14      type: 'line'
15    }]
16  };
17
18  const { chartRef } = useEcharts({
19    option: options
20  });
21
22  return <div ref={chartRef} style={{ width: '100%', height: '300px' }} />;
23}

📖 API

useEcharts

The main hook for using ECharts in React components.

1const { chartRef, setOption, getInstance } = useEcharts({
2  option: UseEchartsOptions['option'];      // ECharts options configuration (required)
3  theme?: string | object;    // ECharts theme name or configuration
4  notMerge?: boolean;        // Whether to not merge with previous options
5  lazyUpdate?: boolean;      // Whether to update chart lazily
6  showLoading?: boolean;     // Whether to display loading animation
7  loadingOption?: object;    // Loading animation configuration
8  onEvents?: {              // Event handlers
9    [eventName: string]: {
10      handler: (params: any) => void;
11      query?: string | object;
12      context?: object;
13    }
14  }
15});

Returns

• chartRef: Ref object to attach to the chart container
• setOption: Function to update chart options
• getInstance: Function to get the ECharts instance (available after component mounts)

🤝 Contributing

We welcome all contributions. Please read our contributing guidelines first. You can submit any ideas as pull requests or as GitHub issues.

📝 Changelog

Detailed changes for each release are documented in the release notes.

📄 License

MIT © chin