1---
2title: Always Declare Emits for Documentation and Validation
3impact: MEDIUM
4impactDescription: Undeclared emits cause warnings, break TypeScript inference, and prevent event validation
5type: best-practice
6tags: [vue3, emits, defineEmits, component-events, typescript, documentation]
7---
8 
9# Always Declare Emits for Documentation and Validation
10 
11**Impact: MEDIUM** - Declaring emitted events with `defineEmits()` or the `emits` option is technically optional, but strongly recommended. Without declarations, Vue shows runtime warnings, TypeScript can't infer event types, and you lose the ability to validate event payloads.
12 
13Declared emits also serve as self-documentation, making it immediately clear what events a component can emit.
14 
15## Task Checklist
16 
17- [ ] Use `defineEmits()` in `<script setup>` to declare all events
18- [ ] Use `emits` option when not using `<script setup>`
19- [ ] Add TypeScript types for event payloads
20- [ ] Consider adding validation functions for complex payloads
21- [ ] Document the purpose of each event
22 
23## The Warning
24 
25When you emit without declaring:
26 
27```vue
28<script setup>
29// No defineEmits declaration
30function handleClick() {
31  emit('select', item) // Vue warns in dev mode
32}
33</script>
34```
35 
36Vue warns:
37```
38[Vue warn]: Component emitted event "select" but it is neither declared
39in the emits option nor as an "onSelect" prop.
40```
41 
42## Basic Declaration
43 
44**Correct - Array syntax:**
45```vue
46<script setup>
47const emit = defineEmits(['submit', 'cancel', 'update'])
48 
49function handleSubmit() {
50  emit('submit', formData)
51}
52 
53function handleCancel() {
54  emit('cancel')
55}
56</script>
57```
58 
59**Correct - Options API:**
60```js
61export default {
62  emits: ['submit', 'cancel', 'update'],
63 
64  methods: {
65    handleSubmit() {
66      this.$emit('submit', this.formData)
67    }
68  }
69}
70```
71 
72## TypeScript Typed Emits
73 
74**Correct - Type-based declaration (recommended for TypeScript):**
75```vue
76<script setup lang="ts">
77interface User {
78  id: number
79  name: string
80}
81 
82const emit = defineEmits<{
83  submit: [data: FormData]
84  cancel: []
85  'update:modelValue': [value: string]
86  select: [user: User, index: number]
87}>()
88 
89// Now TypeScript enforces correct payloads
90emit('submit', formData) // OK
91emit('submit') // Error: Expected 1 argument
92emit('select', user) // Error: Expected 2 arguments
93emit('unknown') // Error: Unknown event
94</script>
95```
96 
97**Alternative syntax (Vue 3.3+):**
98```vue
99<script setup lang="ts">
100const emit = defineEmits<{
101  (e: 'submit', data: FormData): void
102  (e: 'cancel'): void
103  (e: 'update:modelValue', value: string): void
104}>()
105</script>
106```
107 
108## Event Validation
109 
110You can validate event payloads at runtime:
111 
112**Correct - Validation functions:**
113```vue
114<script setup>
115const emit = defineEmits({
116  // No validation, just declaration
117  cancel: null,
118 
119  // Validate payload
120  submit: (payload) => {
121    if (!payload.email) {
122      console.warn('Submit event requires email')
123      return false
124    }
125    return true
126  },
127 
128  // Validate with type checking
129  click: (id) => typeof id === 'number'
130})
131</script>
132```
133 
134Returning `false` from a validator logs a console warning but doesn't prevent the event from being emitted.
135 
136## Benefits of Declaring Emits
137 
138### 1. Fallthrough Attribute Separation
139 
140Without declaration, native event listeners fall through to the root element:
141 
142```vue
143<!-- ParentComponent.vue -->
144<ChildComponent @click="handleClick" />
145```
146 
147```vue
148<!-- ChildComponent.vue - WITHOUT emits declaration -->
149<template>
150  <!-- Native click listener falls through to button -->
151  <button>Click me</button>
152</template>
153```
154 
155With declaration, Vue knows it's a component event:
156 
157```vue
158<script setup>
159// Now Vue knows 'click' is a component event, not native
160const emit = defineEmits(['click'])
161</script>
162```
163 
164### 2. Self-Documentation
165 
166```vue
167<script setup>
168// Clear contract: this component emits these events
169const emit = defineEmits<{
170  'row-click': [row: TableRow]
171  'row-select': [row: TableRow, selected: boolean]
172  'page-change': [page: number]
173  'sort-change': [column: string, direction: 'asc' | 'desc']
174}>()
175</script>
176```
177 
178### 3. IDE Support
179 
180With declarations, your IDE can:
181- Autocomplete event names when using the component
182- Show event payload types
183- Warn about typos in event names
184- Navigate to event definitions
185 
186## $emit in Template vs emit in Script
187 
188```vue
189<script setup>
190// $emit is available in template, but...
191// emit() is needed in <script setup>
192const emit = defineEmits(['submit'])
193 
194function handleSubmit() {
195  // $emit doesn't work here - use emit()
196  emit('submit', data)
197}
198</script>
199 
200<template>
201  <!-- $emit works in template -->
202  <button @click="$emit('submit', data)">Submit</button>
203 
204  <!-- Or use the declared emit function -->
205  <button @click="emit('submit', data)">Submit</button>
206</template>
207```
208 
209## Reference
210- [Vue.js Component Events - Declaring Emitted Events](https://vuejs.org/guide/components/events.html#declaring-emitted-events)
211- [Vue.js Component Events - Events Validation](https://vuejs.org/guide/components/events.html#events-validation)
212- [Vue 3 Migration - emits Option](https://v3-migration.vuejs.org/breaking-changes/emits-option)
213