0
# Event Utilities
1

2
Event handling utilities for extracting chart elements and datasets from user interaction events. These functions enable interactive features like tooltips, data point highlighting, and click handlers.
3

4
## Capabilities
5

6
### Get Dataset At Event
7

8
Extracts the entire dataset from a mouse click event, useful for highlighting or processing an entire data series.
9

10
```typescript { .api }
11
/**
12
 * Get dataset from mouse click event
13
 * @param chart - Chart.js instance from component ref
14
 * @param event - Mouse click event from chart canvas
15
 * @returns Array of active dataset elements at the event location
16
 */
17
function getDatasetAtEvent(chart: Chart, event: MouseEvent): InteractionItem[];
18
```
19

20
**Usage Example:**
21

22
```typescript
23
import { ref } from 'vue';
24
import { Bar, getDatasetAtEvent } from 'vue-chartjs';
25
import type { ChartComponentRef } from 'vue-chartjs';
26

27
const chartRef = ref<ChartComponentRef>();
28

29
const handleChartClick = (event: MouseEvent) => {
30
  if (chartRef.value?.chart) {
31
    const elements = getDatasetAtEvent(chartRef.value.chart, event);
32
    if (elements.length > 0) {
33
      const datasetIndex = elements[0].datasetIndex;
34
      console.log('Clicked on dataset:', datasetIndex);
35
      // Handle dataset interaction
36
    }
37
  }
38
};
39
```
40

41
### Get Element At Event
42

43
Extracts a single element closest to the mouse click event, ideal for point-specific interactions.
44

45
```typescript { .api }
46
/**
47
 * Get single dataset element from mouse click event
48
 * @param chart - Chart.js instance from component ref
49
 * @param event - Mouse click event from chart canvas
50
 * @returns Array containing the single element nearest to event location
51
 */
52
function getElementAtEvent(chart: Chart, event: MouseEvent): InteractionItem[];
53
```
54

55
**Usage Example:**
56

57
```typescript
58
import { ref } from 'vue';
59
import { Line, getElementAtEvent } from 'vue-chartjs';
60
import type { ChartComponentRef } from 'vue-chartjs';
61

62
const chartRef = ref<ChartComponentRef>();
63

64
const handlePointClick = (event: MouseEvent) => {
65
  if (chartRef.value?.chart) {
66
    const elements = getElementAtEvent(chartRef.value.chart, event);
67
    if (elements.length > 0) {
68
      const { datasetIndex, index } = elements[0];
69
      const value = chartRef.value.chart.data.datasets[datasetIndex].data[index];
70
      console.log('Clicked point value:', value);
71
      // Handle specific data point interaction
72
    }
73
  }
74
};
75
```
76

77
### Get Elements At Event
78

79
Extracts all elements at the same index across all datasets, useful for cross-dataset comparisons at a specific data point.
80

81
```typescript { .api }
82
/**
83
 * Get all dataset elements from mouse click event
84
 * @param chart - Chart.js instance from component ref
85
 * @param event - Mouse click event from chart canvas
86
 * @returns Array of all elements at the same index as the event location
87
 */
88
function getElementsAtEvent(chart: Chart, event: MouseEvent): InteractionItem[];
89
```
90

91
**Usage Example:**
92

93
```typescript
94
import { ref } from 'vue';
95
import { Bar, getElementsAtEvent } from 'vue-chartjs';
96
import type { ChartComponentRef } from 'vue-chartjs';
97

98
const chartRef = ref<ChartComponentRef>();
99

100
const handleCategoryClick = (event: MouseEvent) => {
101
  if (chartRef.value?.chart) {
102
    const elements = getElementsAtEvent(chartRef.value.chart, event);
103
    if (elements.length > 0) {
104
      const index = elements[0].index;
105
      const label = chartRef.value.chart.data.labels?.[index];
106
      console.log('Clicked category:', label);
107
      
108
      // Process all datasets at this index
109
      elements.forEach((element) => {
110
        const dataset = chartRef.value.chart.data.datasets[element.datasetIndex];
111
        const value = dataset.data[element.index];
112
        console.log(`${dataset.label}: ${value}`);
113
      });
114
    }
115
  }
116
};
117
```
118

119
## Vue Template Integration
120

121
These utilities are commonly used with Vue event handlers on chart components:
122

123
```vue
124
<template>
125
  <div>
126
    <Bar 
127
      ref="chartRef"
128
      :data="chartData" 
129
      :options="chartOptions"
130
      @click="handleChartClick"
131
    />
132
  </div>
133
</template>
134

135
<script setup lang="ts">
136
import { ref } from 'vue';
137
import { Bar, getElementAtEvent } from 'vue-chartjs';
138
import type { ChartComponentRef } from 'vue-chartjs';
139

140
const chartRef = ref<ChartComponentRef>();
141

142
const handleChartClick = (event: MouseEvent) => {
143
  if (chartRef.value?.chart) {
144
    const elements = getElementAtEvent(chartRef.value.chart, event);
145
    // Handle click interaction
146
  }
147
};
148
</script>
149
```
150

151
## Types
152

153
```typescript { .api }
154
// Re-exported from Chart.js
155
interface InteractionItem {
156
  datasetIndex: number;
157
  index: number;
158
}
159

160
// Chart.js Chart type (available via chart component ref)
161
import type { Chart, InteractionItem } from 'chart.js';
162
```