0
# Vue-ChartJS
1

2
Vue-ChartJS is a wrapper for Chart.js in Vue that enables developers to create reusable, reactive chart components. It provides pre-built chart components for all Chart.js chart types with full Vue reactivity integration, supporting both Vue 2.7+ and Vue 3 with Chart.js v4.
3

4
## Package Information
5

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

11
## Core Imports
12

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

20
For CommonJS:
21

22
```javascript
23
const { Chart, Bar, Line, Pie, Doughnut, PolarArea, Radar, Bubble, Scatter } = require("vue-chartjs");
24
const { getDatasetAtEvent, getElementAtEvent, getElementsAtEvent } = require("vue-chartjs");
25
```
26

27
## Basic Usage
28

29
```vue
30
<template>
31
  <Bar 
32
    :data="data" 
33
    :options="options"
34
    aria-label="Sales data chart showing quarterly performance"
35
    aria-describedby="chart-description"
36
  />
37
  <div id="chart-description" class="sr-only">
38
    Bar chart displaying sales data across three quarters: January ($40k), February ($20k), and March ($12k).
39
  </div>
40
</template>
41

42
<script setup lang="ts">
43
import { ref } from 'vue';
44
import {
45
  Chart as ChartJS,
46
  Title,
47
  Tooltip,
48
  Legend,
49
  BarElement,
50
  CategoryScale,
51
  LinearScale
52
} from 'chart.js';
53
import { Bar } from 'vue-chartjs';
54

55
ChartJS.register(CategoryScale, LinearScale, BarElement, Title, Tooltip, Legend);
56

57
const data = ref({
58
  labels: ['January', 'February', 'March'],
59
  datasets: [{
60
    label: 'Sales',
61
    data: [40, 20, 12],
62
    backgroundColor: '#f87979'
63
  }]
64
});
65

66
const options = ref({
67
  responsive: true,
68
  maintainAspectRatio: false
69
});
70
</script>
71
```
72

73
## Architecture
74

75
Vue-ChartJS is built around several key components:
76

77
- **Generic Chart Component**: Base `Chart` component accepting any Chart.js chart type via `type` prop
78
- **Typed Chart Components**: Pre-configured components (`Bar`, `Line`, `Pie`, etc.) with automatic Chart.js registration
79
- **Reactivity System**: Full Vue reactivity integration with intelligent update mechanisms
80
- **Event System**: Chart.js event handling utilities for user interactions
81
- **Type Safety**: Complete TypeScript support with generic type preservation
82
- **Vue Compatibility**: Support for both Vue 2.7+ and Vue 3 through compatibility layers
83

84
## Capabilities
85

86
### Chart Components
87

88
Provides both generic and typed chart components with full Chart.js integration and Vue reactivity.
89

90
```typescript { .api }
91
// Generic chart component
92
const Chart: ChartComponent;
93

94
// Typed chart components  
95
const Bar: TypedChartComponent<'bar'>;
96
const Line: TypedChartComponent<'line'>;
97
const Pie: TypedChartComponent<'pie'>;
98
const Doughnut: TypedChartComponent<'doughnut'>;
99
const PolarArea: TypedChartComponent<'polarArea'>;
100
const Radar: TypedChartComponent<'radar'>;
101
const Bubble: TypedChartComponent<'bubble'>;
102
const Scatter: TypedChartComponent<'scatter'>;
103

104
interface ChartProps<
105
  TType extends ChartType = ChartType,
106
  TData = DefaultDataPoint<TType>,
107
  TLabel = unknown
108
> {
109
  type: TType; // Required for Chart component only
110
  data: ChartData<TType, TData, TLabel>; // Required
111
  options?: ChartOptions<TType>; // Optional, defaults to {}
112
  plugins?: Plugin<TType>[]; // Optional, defaults to []
113
  datasetIdKey?: string; // Optional, defaults to 'label'
114
  updateMode?: UpdateMode; // Optional
115
  destroyDelay?: number; // Optional, defaults to 0 - delay before destroying chart instance
116
  ariaLabel?: string; // Optional - ARIA label for accessibility
117
  ariaDescribedby?: string; // Optional - ARIA described-by for accessibility
118
}
119

120
interface ChartComponentRef<
121
  TType extends ChartType = ChartType,
122
  TData = DefaultDataPoint<TType>,
123
  TLabel = unknown
124
> {
125
  chart: ChartJS<TType, TData, TLabel> | null;
126
}
127

128
type ChartComponent = DefineComponent<ChartProps>;
129

130
type TypedChartComponent<
131
  TType extends ChartType,
132
  TData = DefaultDataPoint<TType>,
133
  TLabel = unknown
134
> = DefineComponent<Omit<ChartProps<TType, TData, TLabel>, 'type'>>;
135
```
136

137
### Chart Factory
138

139
Factory function for creating custom typed chart components with automatic Chart.js registration.
140

141
```typescript { .api }
142
/**
143
 * Creates a typed chart component with automatic Chart.js registration
144
 * @param type - Chart.js chart type
145
 * @param registerables - Chart.js components to register
146
 * @returns TypedChartComponent for the specified chart type
147
 */
148
function createTypedChart<
149
  TType extends ChartType = ChartType,
150
  TData = DefaultDataPoint<TType>,
151
  TLabel = unknown
152
>(
153
  type: TType,
154
  registerables: ChartComponentLike
155
): TypedChartComponent<TType, TData, TLabel>;
156
```
157

158
### Accessibility Features
159

160
Chart components support accessibility through ARIA attributes and chart lifecycle management.
161

162
```typescript { .api }
163
interface AccessibilityProps {
164
  /** ARIA label for the chart canvas element */
165
  ariaLabel?: string;
166
  /** ARIA described-by reference for detailed chart description */
167
  ariaDescribedby?: string;
168
  /** Delay in milliseconds before destroying chart instance (prevents memory leaks) */
169
  destroyDelay?: number; // defaults to 0
170
}
171
```
172

173
### Event Handling Utilities
174

175
Utilities for extracting chart elements and datasets from user interaction events.
176

177
```typescript { .api }
178
/**
179
 * Get dataset from mouse click event
180
 * @param chart - Chart.js instance
181
 * @param event - Mouse click event
182
 * @returns Dataset elements at event location
183
 */
184
function getDatasetAtEvent(chart: Chart, event: MouseEvent): InteractionItem[];
185

186
/**
187
 * Get single dataset element from mouse click event
188
 * @param chart - Chart.js instance  
189
 * @param event - Mouse click event
190
 * @returns Single element nearest to event location
191
 */
192
function getElementAtEvent(chart: Chart, event: MouseEvent): InteractionItem[];
193

194
/**
195
 * Get all dataset elements from mouse click event
196
 * @param chart - Chart.js instance
197
 * @param event - Mouse click event  
198
 * @returns All elements at the same index as event location
199
 */
200
function getElementsAtEvent(chart: Chart, event: MouseEvent): InteractionItem[];
201
```
202

203
[Event Utilities](./event-utilities.md)
204

205
## Types
206

207
```typescript { .api }
208
// Extended data point interface for complex data structures (used in typed chart components like Bar)
209
interface ExtendedDataPoint {
210
  [key: string]: string | number | null | ExtendedDataPoint;
211
}
212

213
// Re-exported Chart.js types
214
import type {
215
  Chart,
216
  ChartType,
217
  ChartData,
218
  ChartDataset,
219
  ChartOptions,
220
  DefaultDataPoint,
221
  Plugin,
222
  UpdateMode,
223
  InteractionItem,
224
  ChartComponentLike
225
} from 'chart.js';
226
```