0
# Chart Components
1

2
React components for rendering different types of Chart.js charts. All components are React forwardRef components that provide access to the underlying Chart.js instance.
3

4
## Capabilities
5

6
### Generic Chart Component
7

8
A flexible component that can render any Chart.js chart type by specifying the `type` prop.
9

10
```typescript { .api }
11
/**
12
 * Generic chart component that accepts any Chart.js chart type
13
 * @param props - Chart configuration including type, data, and options
14
 * @returns JSX.Element representing the chart canvas
15
 */
16
function Chart<
17
  TType extends ChartType = ChartType,
18
  TData = DefaultDataPoint<TType>,
19
  TLabel = unknown,
20
>(props: ChartProps<TType, TData, TLabel> & {
21
  ref?: ForwardedRef<ChartJSOrUndefined<TType, TData, TLabel>>;
22
}): JSX.Element;
23

24
interface ChartProps<
25
  TType extends ChartType = ChartType,
26
  TData = DefaultDataPoint<TType>,
27
  TLabel = unknown,
28
> extends CanvasHTMLAttributes<HTMLCanvasElement> {
29
  /** Chart.js chart type (required) */
30
  type: TType;
31
  /** The data object that is passed into the Chart.js chart (required) */
32
  data: ChartData<TType, TData, TLabel>;
33
  /** The options object that is passed into the Chart.js chart */
34
  options?: ChartOptions<TType>;
35
  /** The plugins array that is passed into the Chart.js chart */
36
  plugins?: Plugin<TType>[];
37
  /** Teardown and redraw chart on every update (default: false) */
38
  redraw?: boolean;
39
  /** Key name to identificate dataset (default: 'label') */
40
  datasetIdKey?: string;
41
  /** A fallback for when the canvas cannot be rendered */
42
  fallbackContent?: ReactNode;
43
  /** A mode string to indicate transition configuration should be used */
44
  updateMode?: UpdateMode;
45
}
46
```
47

48
**Usage Examples:**
49

50
```typescript
51
import React, { useRef } from "react";
52
import { Chart } from "react-chartjs-2";
53
import type { Chart as ChartJS } from "chart.js";
54

55
function MyGenericChart() {
56
  const chartRef = useRef<ChartJS>(null);
57

58
  const data = {
59
    labels: ['A', 'B', 'C'],
60
    datasets: [{
61
      label: 'Dataset',
62
      data: [1, 2, 3],
63
    }],
64
  };
65

66
  return (
67
    <Chart
68
      ref={chartRef}
69
      type="bar"
70
      data={data}
71
      options={{ responsive: true }}
72
    />
73
  );
74
}
75
```
76

77
### Line Chart Component
78

79
Pre-configured component for rendering line charts.
80

81
```typescript { .api }
82
/**
83
 * Line chart component with Chart.js line controller pre-registered
84
 * @param props - Chart configuration without type prop (type is 'line')
85
 * @returns JSX.Element representing the line chart canvas
86
 */
87
function Line<
88
  TData = DefaultDataPoint<'line'>,
89
  TLabel = unknown,
90
>(props: Omit<ChartProps<'line', TData, TLabel>, 'type'> & {
91
  ref?: ForwardedRef<ChartJSOrUndefined<'line', TData, TLabel>>;
92
}): JSX.Element;
93
```
94

95
**Usage Examples:**
96

97
```typescript
98
import React from "react";
99
import { Line } from "react-chartjs-2";
100
import {
101
  Chart as ChartJS,
102
  CategoryScale,
103
  LinearScale,
104
  PointElement,
105
  LineElement,
106
} from 'chart.js';
107

108
ChartJS.register(CategoryScale, LinearScale, PointElement, LineElement);
109

110
function LineChartExample() {
111
  const data = {
112
    labels: ['Jan', 'Feb', 'Mar', 'Apr', 'May'],
113
    datasets: [{
114
      label: 'Sales',
115
      data: [65, 59, 80, 81, 56],
116
      borderColor: 'rgb(75, 192, 192)',
117
      backgroundColor: 'rgba(75, 192, 192, 0.2)',
118
    }],
119
  };
120

121
  return <Line data={data} options={{ responsive: true }} />;
122
}
123
```
124

125
### Bar Chart Component
126

127
Pre-configured component for rendering bar charts.
128

129
```typescript { .api }
130
/**
131
 * Bar chart component with Chart.js bar controller pre-registered
132
 * @param props - Chart configuration without type prop (type is 'bar')
133
 * @returns JSX.Element representing the bar chart canvas
134
 */
135
function Bar<
136
  TData = DefaultDataPoint<'bar'>,
137
  TLabel = unknown,
138
>(props: Omit<ChartProps<'bar', TData, TLabel>, 'type'> & {
139
  ref?: ForwardedRef<ChartJSOrUndefined<'bar', TData, TLabel>>;
140
}): JSX.Element;
141
```
142

143
### Radar Chart Component
144

145
Pre-configured component for rendering radar charts.
146

147
```typescript { .api }
148
/**
149
 * Radar chart component with Chart.js radar controller pre-registered
150
 * @param props - Chart configuration without type prop (type is 'radar')
151
 * @returns JSX.Element representing the radar chart canvas
152
 */
153
function Radar<
154
  TData = DefaultDataPoint<'radar'>,
155
  TLabel = unknown,
156
>(props: Omit<ChartProps<'radar', TData, TLabel>, 'type'> & {
157
  ref?: ForwardedRef<ChartJSOrUndefined<'radar', TData, TLabel>>;
158
}): JSX.Element;
159
```
160

161
### Doughnut Chart Component
162

163
Pre-configured component for rendering doughnut charts.
164

165
```typescript { .api }
166
/**
167
 * Doughnut chart component with Chart.js doughnut controller pre-registered
168
 * @param props - Chart configuration without type prop (type is 'doughnut')
169
 * @returns JSX.Element representing the doughnut chart canvas
170
 */
171
function Doughnut<
172
  TData = DefaultDataPoint<'doughnut'>,
173
  TLabel = unknown,
174
>(props: Omit<ChartProps<'doughnut', TData, TLabel>, 'type'> & {
175
  ref?: ForwardedRef<ChartJSOrUndefined<'doughnut', TData, TLabel>>;
176
}): JSX.Element;
177
```
178

179
**Usage Examples:**
180

181
```typescript
182
import React from "react";
183
import { Doughnut } from "react-chartjs-2";
184
import { Chart as ChartJS, ArcElement, Tooltip, Legend } from 'chart.js';
185

186
ChartJS.register(ArcElement, Tooltip, Legend);
187

188
function DoughnutExample() {
189
  const data = {
190
    labels: ['Red', 'Blue', 'Yellow'],
191
    datasets: [{
192
      data: [300, 50, 100],
193
      backgroundColor: ['#FF6384', '#36A2EB', '#FFCE56'],
194
    }],
195
  };
196

197
  return (
198
    <Doughnut 
199
      data={data} 
200
      options={{ 
201
        cutout: '60%',
202
        plugins: { legend: { position: 'bottom' } }
203
      }} 
204
    />
205
  );
206
}
207
```
208

209
### Polar Area Chart Component 
210

211
Pre-configured component for rendering polar area charts.
212

213
```typescript { .api }
214
/**
215
 * Polar area chart component with Chart.js polar area controller pre-registered
216
 * @param props - Chart configuration without type prop (type is 'polarArea')
217
 * @returns JSX.Element representing the polar area chart canvas
218
 */
219
function PolarArea<
220
  TData = DefaultDataPoint<'polarArea'>,
221
  TLabel = unknown,
222
>(props: Omit<ChartProps<'polarArea', TData, TLabel>, 'type'> & {
223
  ref?: ForwardedRef<ChartJSOrUndefined<'polarArea', TData, TLabel>>;
224
}): JSX.Element;
225
```
226

227
### Bubble Chart Component
228

229
Pre-configured component for rendering bubble charts.
230

231
```typescript { .api }
232
/**
233
 * Bubble chart component with Chart.js bubble controller pre-registered
234
 * @param props - Chart configuration without type prop (type is 'bubble')
235
 * @returns JSX.Element representing the bubble chart canvas
236
 */
237
function Bubble<
238
  TData = DefaultDataPoint<'bubble'>,
239
  TLabel = unknown,
240
>(props: Omit<ChartProps<'bubble', TData, TLabel>, 'type'> & {
241
  ref?: ForwardedRef<ChartJSOrUndefined<'bubble', TData, TLabel>>;
242
}): JSX.Element;
243
```
244

245
### Pie Chart Component
246

247
Pre-configured component for rendering pie charts.
248

249
```typescript { .api }
250
/**
251
 * Pie chart component with Chart.js pie controller pre-registered
252
 * @param props - Chart configuration without type prop (type is 'pie')
253
 * @returns JSX.Element representing the pie chart canvas
254
 */
255
function Pie<
256
  TData = DefaultDataPoint<'pie'>,
257
  TLabel = unknown,
258
>(props: Omit<ChartProps<'pie', TData, TLabel>, 'type'> & {
259
  ref?: ForwardedRef<ChartJSOrUndefined<'pie', TData, TLabel>>;
260
}): JSX.Element;
261
```
262

263
### Scatter Chart Component
264

265
Pre-configured component for rendering scatter charts.
266

267
```typescript { .api }
268
/**
269
 * Scatter chart component with Chart.js scatter controller pre-registered
270
 * @param props - Chart configuration without type prop (type is 'scatter')
271
 * @returns JSX.Element representing the scatter chart canvas
272
 */
273
function Scatter<
274
  TData = DefaultDataPoint<'scatter'>,
275
  TLabel = unknown,
276
>(props: Omit<ChartProps<'scatter', TData, TLabel>, 'type'> & {
277
  ref?: ForwardedRef<ChartJSOrUndefined<'scatter', TData, TLabel>>;
278
}): JSX.Element;
279
```
280

281
## Common Props
282

283
All chart components accept the same props (except `type` is omitted from typed components):
284

285
- **data** (required): Chart.js data object containing labels and datasets
286
- **options**: Chart.js configuration options for customizing chart appearance and behavior
287
- **plugins**: Array of Chart.js plugins to extend functionality
288
- **redraw**: Boolean to force complete chart redraw on updates (default: false)
289
- **datasetIdKey**: String key for identifying datasets during updates (default: 'label')
290
- **fallbackContent**: React node to display when chart cannot render (accessibility)
291
- **updateMode**: Chart.js update mode for transitions
292
- **width**: Canvas width in pixels (default: 300)
293
- **height**: Canvas height in pixels (default: 150)
294
- Plus all standard HTML canvas attributes
295

296
## Chart.js Registration
297

298
All typed chart components automatically register their required Chart.js controllers, but you must register scales, elements, and plugins separately:
299

300
```typescript
301
import {
302
  Chart as ChartJS,
303
  CategoryScale,
304
  LinearScale,
305
  PointElement,
306
  LineElement,
307
  BarElement,
308
  ArcElement,
309
  Title,
310
  Tooltip,
311
  Legend,
312
} from 'chart.js';
313

314
// Register components you need
315
ChartJS.register(
316
  CategoryScale,
317
  LinearScale,
318
  PointElement,
319
  LineElement,
320
  BarElement,
321
  ArcElement,
322
  Title,
323
  Tooltip,
324
  Legend
325
);
326
```
327

328
## Types
329

330
```typescript { .api }
331
import type { Chart, ChartType, DefaultDataPoint } from 'chart.js';
332

333
type ChartJSOrUndefined<
334
  TType extends ChartType = ChartType,
335
  TData = DefaultDataPoint<TType>,
336
  TLabel = unknown,
337
> = Chart<TType, TData, TLabel> | undefined;
338

339
type ForwardedRef<T> =
340
  | ((instance: T | null) => void)
341
  | MutableRefObject<T | null>
342
  | null;
343

344
type BaseChartComponent = <
345
  TType extends ChartType = ChartType,
346
  TData = DefaultDataPoint<TType>,
347
  TLabel = unknown,
348
>(
349
  props: ChartProps<TType, TData, TLabel> & {
350
    ref?: ForwardedRef<ChartJSOrUndefined<TType, TData, TLabel>>;
351
  }
352
) => JSX.Element;
353

354
type TypedChartComponent<TDefaultType extends ChartType> = <
355
  TData = DefaultDataPoint<TDefaultType>,
356
  TLabel = unknown,
357
>(
358
  props: Omit<ChartProps<TDefaultType, TData, TLabel>, 'type'> & {
359
    ref?: ForwardedRef<ChartJSOrUndefined<TDefaultType, TData, TLabel>>;
360
  }
361
) => JSX.Element;
362
```