1---
2title: Click Events on Custom Components Require Emit or Fallthrough
3impact: HIGH
4impactDescription: Native click events on custom components won't work without proper emit declaration or attribute fallthrough
5type: gotcha
6tags: [vue3, events, components, emit, click, migration]
7---
8 
9# Click Events on Custom Components Require Emit or Fallthrough
10 
11**Impact: HIGH** - Unlike native HTML elements, custom Vue components don't automatically forward native DOM events like `click`. You must either emit the event explicitly, rely on attribute fallthrough to a single root element, or use the `.native` modifier (Vue 2 only, removed in Vue 3). This is a common source of confusion and migration issues.
12 
13## Task Checklist
14 
15- [ ] Declare emitted events using `defineEmits` in child components
16- [ ] Emit click events from child component when needed
17- [ ] Understand that single-root components automatically forward attrs to root
18- [ ] Remove `.native` modifier when migrating from Vue 2 to Vue 3
19- [ ] For multi-root components, explicitly bind `$attrs` or emit events
20 
21**Incorrect:**
22```html
23<!-- WRONG: Expecting native click to work on custom component -->
24<template>
25  <MyButton @click="handleClick">Click me</MyButton>
26  <!-- This may not work as expected! -->
27</template>
28```
29 
30```html
31<!-- WRONG: Vue 2 .native modifier doesn't exist in Vue 3 -->
32<template>
33  <MyButton @click.native="handleClick">Click me</MyButton>
34  <!-- Error in Vue 3: .native modifier removed -->
35</template>
36```
37 
38```html
39<!-- WRONG: Multi-root component with no attr binding -->
40<!-- MyButton.vue -->
41<template>
42  <span>Icon</span>
43  <button>{{ label }}</button>
44  <!-- No root element to receive click! -->
45</template>
46```
47 
48**Correct:**
49```html
50<!-- CORRECT: Child component emits the click event -->
51<!-- MyButton.vue -->
52<template>
53  <button @click="$emit('click', $event)">
54    <slot></slot>
55  </button>
56</template>
57 
58<script setup>
59defineEmits(['click'])
60</script>
61 
62<!-- Parent.vue -->
63<template>
64  <MyButton @click="handleClick">Click me</MyButton>
65</template>
66```
67 
68```html
69<!-- CORRECT: Single root element with automatic fallthrough -->
70<!-- MyButton.vue -->
71<template>
72  <button>
73    <slot></slot>
74  </button>
75  <!-- @click from parent automatically falls through to button -->
76</template>
77 
78<!-- Parent.vue -->
79<template>
80  <MyButton @click="handleClick">Click me</MyButton>
81</template>
82```
83 
84```html
85<!-- CORRECT: Multi-root component with explicit $attrs binding -->
86<!-- MyButton.vue -->
87<template>
88  <span>Icon</span>
89  <button v-bind="$attrs">
90    <slot></slot>
91  </button>
92</template>
93 
94<script setup>
95defineOptions({
96  inheritAttrs: false
97})
98</script>
99```
100 
101## Component Events Don't Bubble
102 
103```javascript
104// Important: Component-emitted events do NOT bubble
105// You can only listen to events from direct children
106 
107// WRONG: Trying to catch grandchild events
108<GrandParent @child-event="handle">  <!-- Won't receive! -->
109  <Parent>
110    <Child @click="$emit('child-event')" />
111  </Parent>
112</GrandParent>
113 
114// CORRECT: Each level must relay the event
115<GrandParent @child-event="handle">
116  <Parent @child-event="$emit('child-event', $event)">
117    <Child @click="$emit('child-event')" />
118  </Parent>
119</GrandParent>
120```
121 
122## Vue 3 Native Event Behavior
123 
124```javascript
125// In Vue 3, if you declare an event in emits:
126defineEmits(['click'])
127 
128// Then @click on the component ONLY listens to emitted events
129// NOT native click events
130 
131// If you don't declare 'click' in emits:
132defineEmits(['custom-event'])
133 
134// Then @click on single-root component will:
135// 1. Fall through to root element as native listener
136// 2. Fire on native click
137```
138 
139## Composition API Emit Pattern
140 
141```vue
142<script setup>
143// Define what events this component emits
144const emit = defineEmits(['click', 'update', 'delete'])
145 
146function handleClick(event) {
147  // Do component logic
148  processClick()
149 
150  // Then emit to parent
151  emit('click', event)
152}
153</script>
154 
155<template>
156  <button @click="handleClick">
157    <slot></slot>
158  </button>
159</template>
160```
161 
162## Migration from Vue 2
163 
164```html
165<!-- Vue 2: Used .native for native events on components -->
166<MyComponent @click.native="handleClick" />
167 
168<!-- Vue 3: Remove .native, ensure component handles the event -->
169<MyComponent @click="handleClick" />
170 
171<!-- Make sure MyComponent either:
172     1. Has single root that receives fallthrough attrs
173     2. Explicitly emits 'click' event
174     3. Uses v-bind="$attrs" on intended element -->
175```
176 
177## Reference
178- [Vue.js Component Events](https://vuejs.org/guide/components/events.html)
179- [Vue.js Fallthrough Attributes](https://vuejs.org/guide/components/attrs.html)
180- [Vue 3 Migration - .native Modifier Removed](https://v3-migration.vuejs.org/breaking-changes/v-on-native-modifier-removed.html)
181