1---
2title: Always Explicitly Type Event Handlers
3impact: MEDIUM
4impactDescription: Without explicit typing, event parameters have implicit 'any' type causing TypeScript errors in strict mode
5type: gotcha
6tags: [vue3, typescript, events, dom-events, composition-api]
7---
8 
9# Always Explicitly Type Event Handlers
10 
11**Impact: MEDIUM** - Native DOM event handlers in Vue components have implicit `any` type for the `event` parameter. In TypeScript strict mode, this causes errors. You must explicitly type event parameters and use type assertions for `event.target`.
12 
13## Task Checklist
14 
15- [ ] Always type the `event` parameter explicitly (e.g., `Event`, `MouseEvent`)
16- [ ] Use type assertions when accessing element-specific properties
17- [ ] Consider using inline handlers for simple cases
18- [ ] Be aware of Vue's synthetic event system
19 
20## The Problem
21 
22```vue
23<script setup lang="ts">
24// WRONG: event has implicit 'any' type
25function handleChange(event) {  // Error in strict mode!
26  console.log(event.target.value)  // Also error: target might be null
27}
28 
29// WRONG: Missing type assertion for element access
30function handleInput(event: Event) {
31  console.log(event.target.value)  // Error: 'value' doesn't exist on EventTarget
32}
33</script>
34 
35<template>
36  <input @change="handleChange" @input="handleInput" />
37</template>
38```
39 
40## The Solution
41 
42```vue
43<script setup lang="ts">
44// CORRECT: Explicit Event type + type assertion
45function handleChange(event: Event) {
46  const target = event.target as HTMLInputElement
47  console.log(target.value)
48}
49 
50// CORRECT: Specific event type when needed
51function handleClick(event: MouseEvent) {
52  console.log(event.clientX, event.clientY)
53}
54 
55function handleKeydown(event: KeyboardEvent) {
56  if (event.key === 'Enter') {
57    submitForm()
58  }
59}
60 
61function handleSubmit(event: SubmitEvent) {
62  event.preventDefault()
63  const formData = new FormData(event.target as HTMLFormElement)
64}
65</script>
66 
67<template>
68  <input @change="handleChange" />
69  <button @click="handleClick">Click</button>
70  <input @keydown="handleKeydown" />
71  <form @submit="handleSubmit">...</form>
72</template>
73```
74 
75## Common Event Types
76 
77| Event | Type | Common Properties |
78|-------|------|-------------------|
79| click, dblclick | `MouseEvent` | clientX, clientY, button |
80| keydown, keyup, keypress | `KeyboardEvent` | key, code, ctrlKey, shiftKey |
81| input, change | `Event` | target (needs assertion) |
82| focus, blur | `FocusEvent` | relatedTarget |
83| submit | `SubmitEvent` | submitter |
84| drag, dragstart, drop | `DragEvent` | dataTransfer |
85| wheel, scroll | `WheelEvent` | deltaX, deltaY |
86| touch events | `TouchEvent` | touches, changedTouches |
87 
88## Element-Specific Type Assertions
89 
90```vue
91<script setup lang="ts">
92// HTMLInputElement for text, number, checkbox, radio inputs
93function handleTextInput(event: Event) {
94  const input = event.target as HTMLInputElement
95  console.log(input.value, input.checked)
96}
97 
98// HTMLSelectElement for select dropdowns
99function handleSelect(event: Event) {
100  const select = event.target as HTMLSelectElement
101  console.log(select.value, select.selectedIndex)
102}
103 
104// HTMLTextAreaElement for textareas
105function handleTextarea(event: Event) {
106  const textarea = event.target as HTMLTextAreaElement
107  console.log(textarea.value, textarea.selectionStart)
108}
109 
110// HTMLFormElement for forms
111function handleFormSubmit(event: SubmitEvent) {
112  event.preventDefault()
113  const form = event.target as HTMLFormElement
114  const formData = new FormData(form)
115}
116</script>
117```
118 
119## Inline Event Handler Pattern
120 
121For simple cases, inline handlers with type annotations work well:
122 
123```vue
124<template>
125  <!-- Inline with type assertion -->
126  <input
127    @input="(event: Event) => {
128      const input = event.target as HTMLInputElement
129      searchQuery = input.value
130    }"
131  />
132 
133  <!-- Or with $event cast -->
134  <input @input="searchQuery = ($event.target as HTMLInputElement).value" />
135</template>
136```
137 
138## Generic Handler Pattern
139 
140Create reusable typed handlers:
141 
142```typescript
143// utils/events.ts
144export function getInputValue(event: Event): string {
145  return (event.target as HTMLInputElement).value
146}
147 
148export function getSelectValue(event: Event): string {
149  return (event.target as HTMLSelectElement).value
150}
151 
152export function getCheckboxChecked(event: Event): boolean {
153  return (event.target as HTMLInputElement).checked
154}
155```
156 
157```vue
158<script setup lang="ts">
159import { getInputValue, getCheckboxChecked } from '@/utils/events'
160 
161const name = ref('')
162const agreed = ref(false)
163</script>
164 
165<template>
166  <input @input="e => name = getInputValue(e)" />
167  <input type="checkbox" @change="e => agreed = getCheckboxChecked(e)" />
168</template>
169```
170 
171## Vue Component Events
172 
173For Vue component events (not DOM events), use `defineEmits` for type safety:
174 
175```vue
176<script setup lang="ts">
177const emit = defineEmits<{
178  'custom-event': [data: { id: number; name: string }]
179}>()
180 
181// Handler for child component event
182function handleChildEvent(data: { id: number; name: string }) {
183  console.log(data.id, data.name)
184}
185</script>
186 
187<template>
188  <!-- Custom component event - properly typed -->
189  <ChildComponent @custom-event="handleChildEvent" />
190</template>
191```
192 
193## Avoiding currentTarget vs target Confusion
194 
195```typescript
196function handleClick(event: MouseEvent) {
197  // target: The element that triggered the event (could be a child)
198  const target = event.target as HTMLElement
199 
200  // currentTarget: The element the listener is attached to
201  const currentTarget = event.currentTarget as HTMLButtonElement
202 
203  // Be explicit about which you need
204  if (target.tagName === 'SPAN') {
205    // Clicked on span inside button
206  }
207}
208```
209 
210## Reference
211- [Vue.js TypeScript with Composition API - Event Handlers](https://vuejs.org/guide/typescript/composition-api.html#typing-event-handlers)
212- [MDN Event Reference](https://developer.mozilla.org/en-US/docs/Web/Events)
213- [TypeScript DOM Types](https://github.com/microsoft/TypeScript/blob/main/lib/lib.dom.d.ts)
214