0
# React-chartjs-2
1

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.
3

4
## Package Information
5

6
- **Package Name**: react-chartjs-2
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install react-chartjs-2 chart.js`
10

11
## Core Imports
12

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

19
For CommonJS:
20

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

25
You must also install and register Chart.js components:
26

27
```typescript
28
import {
29
  Chart as ChartJS,
30
  CategoryScale,
31
  LinearScale,
32
  PointElement,
33
  LineElement,
34
  Title,
35
  Tooltip,
36
  Legend
37
} from 'chart.js';
38

39
ChartJS.register(
40
  CategoryScale,
41
  LinearScale,
42
  PointElement,
43
  LineElement,
44
  Title,
45
  Tooltip,
46
  Legend
47
);
48
```
49

50
## Basic Usage
51

52
```typescript
53
import React from "react";
54
import { Line } from "react-chartjs-2";
55
import {
56
  Chart as ChartJS,
57
  CategoryScale,
58
  LinearScale,
59
  PointElement,
60
  LineElement,
61
  Title,
62
  Tooltip,
63
  Legend
64
} from 'chart.js';
65

66
ChartJS.register(
67
  CategoryScale,
68
  LinearScale,
69
  PointElement,
70
  LineElement,
71
  Title,
72
  Tooltip,
73
  Legend
74
);
75

76
const data = {
77
  labels: ['January', 'February', 'March', 'April', 'May', 'June'],
78
  datasets: [
79
    {
80
      label: 'Sales',
81
      data: [12, 19, 3, 5, 2, 3],
82
      borderColor: 'rgb(75, 192, 192)',
83
      backgroundColor: 'rgba(75, 192, 192, 0.2)',
84
    },
85
  ],
86
};
87

88
const options = {
89
  responsive: true,
90
  scales: {
91
    y: {
92
      beginAtZero: true,
93
    },
94
  },
95
};
96

97
function MyChart() {
98
  return <Line data={data} options={options} />;
99
}
100
```
101

102
## Architecture
103

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

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

112
## Capabilities
113

114
### Chart Components
115

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

118
```typescript { .api }
119
// Generic chart component
120
interface ChartProps<
121
  TType extends ChartType = ChartType,
122
  TData = DefaultDataPoint<TType>,
123
  TLabel = unknown,
124
> {
125
  type: TType;
126
  data: ChartData<TType, TData, TLabel>;
127
  options?: ChartOptions<TType>;
128
  plugins?: Plugin<TType>[];
129
  redraw?: boolean;
130
  datasetIdKey?: string;
131
  fallbackContent?: ReactNode;
132
  updateMode?: UpdateMode;
133
  width?: number;
134
  height?: number;
135
}
136

137
function Chart<
138
  TType extends ChartType = ChartType,
139
  TData = DefaultDataPoint<TType>,
140
  TLabel = unknown,
141
>(props: ChartProps<TType, TData, TLabel>): JSX.Element;
142

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

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

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

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

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

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

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

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

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

179
### Event Handling
180

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

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

187
function getDatasetAtEvent(
188
  chart: Chart,
189
  event: MouseEvent<HTMLCanvasElement>
190
): InteractionItem[];
191

192
function getElementAtEvent(
193
  chart: Chart,
194
  event: MouseEvent<HTMLCanvasElement>
195
): InteractionItem[];
196

197
function getElementsAtEvent(
198
  chart: Chart,
199
  event: MouseEvent<HTMLCanvasElement>
200
): InteractionItem[];
201
```
202

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

205
## Types
206

207
Core types used across the library:
208

209
```typescript { .api }
210
import type {
211
  ChartType,
212
  ChartData,
213
  ChartOptions,
214
  DefaultDataPoint,
215
  Plugin,
216
  UpdateMode,
217
} from 'chart.js';
218
import type { CanvasHTMLAttributes, ReactNode } from 'react';
219

220
interface ChartProps<
221
  TType extends ChartType = ChartType,
222
  TData = DefaultDataPoint<TType>,
223
  TLabel = unknown,
224
> extends CanvasHTMLAttributes<HTMLCanvasElement> {
225
  /** Chart.js chart type */
226
  type: TType;
227
  /** The data object that is passed into the Chart.js chart */
228
  data: ChartData<TType, TData, TLabel>;
229
  /** The options object that is passed into the Chart.js chart */
230
  options?: ChartOptions<TType>;
231
  /** The plugins array that is passed into the Chart.js chart */
232
  plugins?: Plugin<TType>[];
233
  /** Teardown and redraw chart on every update */
234
  redraw?: boolean;
235
  /** Key name to identificate dataset */
236
  datasetIdKey?: string;
237
  /** A fallback for when the canvas cannot be rendered */
238
  fallbackContent?: ReactNode;
239
  /** A mode string to indicate transition configuration should be used */
240
  updateMode?: UpdateMode;
241
}
242
```