React ECharts Kit

Production-ready React charting library built on Apache ECharts with TypeScript support, SSR compatibility, and comprehensive theming.

Installation

npm install react-echarts-kit
# or
yarn add react-echarts-kit
# or
pnpm add react-echarts-kit

Quick Start

import { BarChart, ThemeProvider } from 'react-echarts-kit';

const data = {
  categories: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri'],
  series: [
    {
      name: 'Sales',
      data: [120, 200, 150, 80, 70],
      color: '#5470c6',
    },
  ],
};

function App() {
  return (
    <ThemeProvider defaultTheme="light">
      <BarChart data={data} width="100%" height={400} />
    </ThemeProvider>
  );
}

Features

• TypeScript First - Full type safety and IntelliSense support
• SSR Safe - Works with Next.js 16+ and other SSR frameworks
• Light/Dark Themes - Built-in theme system with customization
• Responsive - Automatic resizing with ResizeObserver
• Tree Shakeable - Import only what you need
• Multiple Chart Types - Bar, Line, Pie, Area, and Gauge charts

Chart Types

BarChart

import { BarChart } from 'react-echarts-kit';

<BarChart
  data={data}
  width="100%"
  height={400}
  horizontal={false}
  stack={false}
/>

LineChart

import { LineChart } from 'react-echarts-kit';

<LineChart 
  data={data} 
  width="100%" 
  height={400} 
  smooth={true} 
  area={false} 
/>

PieChart

import { PieChart } from 'react-echarts-kit';

<PieChart
  data={data}
  width="100%"
  height={400}
  donut={false}
  showLabels={true}
/>

AreaChart

import { AreaChart } from 'react-echarts-kit';

<AreaChart 
  data={data} 
  width="100%" 
  height={400} 
  stack={true} 
  smooth={true} 
/>

GaugeChart

import { GaugeChart } from 'react-echarts-kit';

<GaugeChart
  data={{ value: 75, min: 0, max: 100, title: 'Progress', unit: '%' }}
  width="100%"
  height={400}
/>

Theming

import { ThemeProvider, useTheme } from 'react-echarts-kit';

function ThemeToggle() {
  const { theme, setTheme } = useTheme();

  return (
    <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
      Toggle Theme
    </button>
  );
}

function App() {
  return (
    <ThemeProvider defaultTheme="dark">
      <ThemeToggle />
      <BarChart data={data} />
    </ThemeProvider>
  );
}

SSR Support (Next.js)

Components work automatically with Next.js:

import { BarChart, LineChart } from 'react-echarts-kit';

export default function Dashboard() {
  return (
    <div>
      <BarChart data={barData} />
      <LineChart data={lineData} />
    </div>
  );
}

For explicit SSR-safe imports:

import { BarChart, LineChart } from 'react-echarts-kit/ssr';

Hooks

useChartData

import { useChartData, BarChart } from 'react-echarts-kit';

function Chart() {
  const { data, setData, isLoading, setLoading } = useChartData(initialData);

  return <BarChart data={data} />;
}

useChartTheme

import { useChartTheme } from 'react-echarts-kit';

function Chart() {
  const { theme, themeConfig, isDark, toggleTheme } = useChartTheme();

  return <div>Current theme: {theme}</div>;
}

useResponsiveChart

import { useResponsiveChart, LineChart } from 'react-echarts-kit';

function Chart() {
  const { containerRef, dimensions } = useResponsiveChart({
    width: '100%',
    height: 400,
  });

  return (
    <div ref={containerRef}>
      <LineChart data={data} width={dimensions.width} height={dimensions.height} />
    </div>
  );
}

API Reference

Common Props

All chart components accept these props:

| Prop | Type | Default | Description | |------|------|---------|-------------| | data | ChartData | Required | Chart data | | width | number \| string | "100%" | Chart width | | height | number \| string | 400 | Chart height | | theme | "light" \| "dark" \| "custom" | "light" | Chart theme | | options | EChartsOption | {} | Custom ECharts options | | onEvents | Record<string, Function> | - | Event handlers |

Data Formats

Simple Data:

const data = [
  { name: 'A', value: 100 },
  { name: 'B', value: 200 },
];

Multi-Series Data:

const data = {
  categories: ['Jan', 'Feb', 'Mar'],
  series: [
    { name: 'Sales', data: [120, 200, 150] },
    { name: 'Profit', data: [20, 50, 30] },
  ],
};

Advanced Usage

Event Handling

<BarChart
  data={data}
  onEvents={{
    click: (params) => console.log('Clicked:', params),
    mouseover: (params) => console.log('Hover:', params),
  }}
/>

Custom ECharts Options

<BarChart
  data={data}
  options={{
    title: { text: 'Custom Title', left: 'center' },
    grid: { left: '10%', right: '10%' },
  }}
/>

TypeScript

Full TypeScript support with exported types:

import type {
  BaseChartProps,
  BarChartData,
  LineChartData,
  PieChartData,
  ThemeType,
  ThemeConfig,
} from 'react-echarts-kit';

Browser Support

• Chrome 60+
• Firefox 55+
• Safari 12+
• Edge 79+

License

MIT © Daniel Lawal

Links

• Documentation
• NPM Package
• Changelog