# React-chartjs-2

React-chartjs-2 is a React wrapper library for Chart.js that provides React components for seamlessly integrating Chart.js charts into React applications. It supports all major chart types and maintains compatibility with Chart.js v4, offering TypeScript support with comprehensive type definitions.

## Package Information

- **Package Name**: react-chartjs-2
- **Package Type**: npm
- **Language**: TypeScript
- **Installation**: `npm install react-chartjs-2 chart.js`

## Core Imports

```typescript
import { Chart, Line, Bar, Radar, Doughnut, PolarArea, Bubble, Pie, Scatter } from "react-chartjs-2";
import { getDatasetAtEvent, getElementAtEvent, getElementsAtEvent } from "react-chartjs-2";
import type { ChartProps } from "react-chartjs-2";
```

For CommonJS:

```javascript
const { Chart, Line, Bar, Radar, Doughnut, PolarArea, Bubble, Pie, Scatter } = require("react-chartjs-2");
```

You must also install and register Chart.js components:

```typescript
import {
  Chart as ChartJS,
  CategoryScale,
  LinearScale,
  PointElement,
  LineElement,
  Title,
  Tooltip,
  Legend
} from 'chart.js';

ChartJS.register(
  CategoryScale,
  LinearScale,
  PointElement,
  LineElement,
  Title,
  Tooltip,
  Legend
);
```

## Basic Usage

```typescript
import React from "react";
import { Line } from "react-chartjs-2";
import {
  Chart as ChartJS,
  CategoryScale,
  LinearScale,
  PointElement,
  LineElement,
  Title,
  Tooltip,
  Legend
} from 'chart.js';

ChartJS.register(
  CategoryScale,
  LinearScale,
  PointElement,
  LineElement,
  Title,
  Tooltip,
  Legend
);

const data = {
  labels: ['January', 'February', 'March', 'April', 'May', 'June'],
  datasets: [
    {
      label: 'Sales',
      data: [12, 19, 3, 5, 2, 3],
      borderColor: 'rgb(75, 192, 192)',
      backgroundColor: 'rgba(75, 192, 192, 0.2)',
    },
  ],
};

const options = {
  responsive: true,
  scales: {
    y: {
      beginAtZero: true,
    },
  },
};

function MyChart() {
  return <Line data={data} options={options} />;
}
```

## Architecture

React-chartjs-2 is built around several key components:

- **Generic Chart Component**: `Chart` component that accepts any Chart.js chart type via the `type` prop
- **Typed Chart Components**: Pre-configured components (`Line`, `Bar`, `Pie`, etc.) for specific chart types
- **Event Utilities**: Helper functions for extracting chart data from user interactions
- **React Integration**: Proper lifecycle management with automatic chart updates when props change
- **Ref Forwarding**: Access to the underlying Chart.js instance via React refs

## Capabilities

### Chart Components

Core chart components for rendering different types of charts. All components support the same props interface with optional chart-specific configurations.

```typescript { .api }
// Generic chart component
interface ChartProps<
  TType extends ChartType = ChartType,
  TData = DefaultDataPoint<TType>,
  TLabel = unknown,
> {
  type: TType;
  data: ChartData<TType, TData, TLabel>;
  options?: ChartOptions<TType>;
  plugins?: Plugin<TType>[];
  redraw?: boolean;
  datasetIdKey?: string;
  fallbackContent?: ReactNode;
  updateMode?: UpdateMode;
  width?: number;
  height?: number;
}

function Chart<
  TType extends ChartType = ChartType,
  TData = DefaultDataPoint<TType>,
  TLabel = unknown,
>(props: ChartProps<TType, TData, TLabel>): JSX.Element;

// Typed chart components (omit 'type' prop)
function Line<TData = DefaultDataPoint<'line'>, TLabel = unknown>(
  props: Omit<ChartProps<'line', TData, TLabel>, 'type'>
): JSX.Element;

function Bar<TData = DefaultDataPoint<'bar'>, TLabel = unknown>(
  props: Omit<ChartProps<'bar', TData, TLabel>, 'type'>
): JSX.Element;

function Radar<TData = DefaultDataPoint<'radar'>, TLabel = unknown>(
  props: Omit<ChartProps<'radar', TData, TLabel>, 'type'>
): JSX.Element;

function Doughnut<TData = DefaultDataPoint<'doughnut'>, TLabel = unknown>(
  props: Omit<ChartProps<'doughnut', TData, TLabel>, 'type'>
): JSX.Element;

function PolarArea<TData = DefaultDataPoint<'polarArea'>, TLabel = unknown>(
  props: Omit<ChartProps<'polarArea', TData, TLabel>, 'type'>
): JSX.Element;

function Bubble<TData = DefaultDataPoint<'bubble'>, TLabel = unknown>(
  props: Omit<ChartProps<'bubble', TData, TLabel>, 'type'>
): JSX.Element;

function Pie<TData = DefaultDataPoint<'pie'>, TLabel = unknown>(
  props: Omit<ChartProps<'pie', TData, TLabel>, 'type'>
): JSX.Element;

function Scatter<TData = DefaultDataPoint<'scatter'>, TLabel = unknown>(
  props: Omit<ChartProps<'scatter', TData, TLabel>, 'type'>
): JSX.Element;
```

[Chart Components](./chart-components.md)

### Event Handling

Utility functions for handling user interactions with charts, extracting chart data from mouse events.

```typescript { .api }
import type { MouseEvent } from 'react';
import type { Chart, InteractionItem } from 'chart.js';

function getDatasetAtEvent(
  chart: Chart,
  event: MouseEvent<HTMLCanvasElement>
): InteractionItem[];

function getElementAtEvent(
  chart: Chart,
  event: MouseEvent<HTMLCanvasElement>
): InteractionItem[];

function getElementsAtEvent(
  chart: Chart,
  event: MouseEvent<HTMLCanvasElement>
): InteractionItem[];
```

[Event Handling](./event-handling.md)

## Types

Core types used across the library:

```typescript { .api }
import type {
  ChartType,
  ChartData,
  ChartOptions,
  DefaultDataPoint,
  Plugin,
  UpdateMode,
} from 'chart.js';
import type { CanvasHTMLAttributes, ReactNode } from 'react';

interface ChartProps<
  TType extends ChartType = ChartType,
  TData = DefaultDataPoint<TType>,
  TLabel = unknown,
> extends CanvasHTMLAttributes<HTMLCanvasElement> {
  /** Chart.js chart type */
  type: TType;
  /** The data object that is passed into the Chart.js chart */
  data: ChartData<TType, TData, TLabel>;
  /** The options object that is passed into the Chart.js chart */
  options?: ChartOptions<TType>;
  /** The plugins array that is passed into the Chart.js chart */
  plugins?: Plugin<TType>[];
  /** Teardown and redraw chart on every update */
  redraw?: boolean;
  /** Key name to identificate dataset */
  datasetIdKey?: string;
  /** A fallback for when the canvas cannot be rendered */
  fallbackContent?: ReactNode;
  /** A mode string to indicate transition configuration should be used */
  updateMode?: UpdateMode;
}
```