1# Use inheritAttrs: false for Wrapper Components
2 
3## Rule
4 
5When building wrapper components where attributes should be applied to an inner element instead of the root element, always set `inheritAttrs: false` and explicitly bind `$attrs` to the target element.
6 
7## Why This Matters
8 
9- By default, Vue applies all non-prop attributes to the root element
10- Wrapper components often have a non-semantic root (div wrapper, label wrapper)
11- Attributes like `id`, `aria-*`, `data-*`, and event listeners should target the functional element
12- Without `inheritAttrs: false`, accessibility and functionality can break
13 
14## Bad Code
15 
16```vue
17<!-- BaseInput.vue - WRONG: attrs go to wrapper div, not input -->
18<template>
19  <div class="input-wrapper">
20    <label>{{ label }}</label>
21    <input type="text" />
22  </div>
23</template>
24 
25<script setup>
26defineProps(['label'])
27</script>
28 
29<!-- Parent usage -->
30<BaseInput
31  id="email"
32  placeholder="Enter email"
33  aria-describedby="email-help"
34  @focus="handleFocus"
35/>
36 
37<!--
38  RESULT: All attrs go to the wrapper div!
39  <div class="input-wrapper" id="email" placeholder="Enter email" ...>
40    <label>...</label>
41    <input type="text" />  <!-- No id, placeholder, or aria! -->
42  </div>
43-->
44```
45 
46## Good Code
47 
48```vue
49<!-- BaseInput.vue - CORRECT: attrs bound to input element -->
50<script setup>
51defineProps(['label'])
52 
53defineOptions({
54  inheritAttrs: false
55})
56</script>
57 
58<template>
59  <div class="input-wrapper">
60    <label>{{ label }}</label>
61    <input type="text" v-bind="$attrs" />
62  </div>
63</template>
64 
65<!-- Parent usage -->
66<BaseInput
67  id="email"
68  placeholder="Enter email"
69  aria-describedby="email-help"
70  @focus="handleFocus"
71/>
72 
73<!--
74  RESULT: Attrs correctly applied to input
75  <div class="input-wrapper">
76    <label>...</label>
77    <input type="text" id="email" placeholder="Enter email"
78           aria-describedby="email-help" />
79  </div>
80-->
81```
82 
83## Setting inheritAttrs in Different Syntaxes
84 
85### Script Setup (Vue 3.3+)
86 
87```vue
88<script setup>
89defineOptions({
90  inheritAttrs: false
91})
92</script>
93```
94 
95### Script Setup (Before Vue 3.3)
96 
97```vue
98<script>
99export default {
100  inheritAttrs: false
101}
102</script>
103 
104<script setup>
105// Your setup code here
106</script>
107```
108 
109### Options API
110 
111```vue
112<script>
113export default {
114  inheritAttrs: false,
115  // other options...
116}
117</script>
118```
119 
120## Common Wrapper Component Patterns
121 
122### Form Input Wrapper
123 
124```vue
125<script setup>
126import { useAttrs, computed } from 'vue'
127 
128defineProps({
129  label: String,
130  error: String
131})
132 
133defineOptions({
134  inheritAttrs: false
135})
136 
137const attrs = useAttrs()
138 
139// Separate class/style for wrapper vs input
140const inputAttrs = computed(() => {
141  const { class: _, style: __, ...rest } = attrs
142  return rest
143})
144</script>
145 
146<template>
147  <div class="form-field" :class="{ 'has-error': error }">
148    <label v-if="label">{{ label }}</label>
149    <input v-bind="inputAttrs" />
150    <span v-if="error" class="error">{{ error }}</span>
151  </div>
152</template>
153```
154 
155### Button with Icon Wrapper
156 
157```vue
158<script setup>
159defineProps({
160  icon: String,
161  iconPosition: {
162    type: String,
163    default: 'left'
164  }
165})
166 
167defineOptions({
168  inheritAttrs: false
169})
170</script>
171 
172<template>
173  <button class="icon-button" v-bind="$attrs">
174    <span v-if="icon && iconPosition === 'left'" class="icon">{{ icon }}</span>
175    <slot />
176    <span v-if="icon && iconPosition === 'right'" class="icon">{{ icon }}</span>
177  </button>
178</template>
179```
180 
181### Link Wrapper Component
182 
183```vue
184<script setup>
185defineProps({
186  to: String,
187  external: Boolean
188})
189 
190defineOptions({
191  inheritAttrs: false
192})
193</script>
194 
195<template>
196  <a
197    v-if="external"
198    :href="to"
199    target="_blank"
200    rel="noopener noreferrer"
201    v-bind="$attrs"
202  >
203    <slot />
204  </a>
205  <router-link v-else :to="to" v-bind="$attrs">
206    <slot />
207  </router-link>
208</template>
209```
210 
211## When NOT to Use inheritAttrs: false
212 
213- Simple components with a single semantic root element
214- Components where the root element should receive all attributes
215- Components that don't wrap other functional elements
216 
217```vue
218<!-- SimpleCard.vue - No need for inheritAttrs: false -->
219<template>
220  <article class="card">
221    <slot />
222  </article>
223</template>
224<!-- Passing class, id, or data-* to the root article is fine -->
225```
226 
227## References
228 
229- [Fallthrough Attributes - Disabling Attribute Inheritance](https://vuejs.org/guide/components/attrs.html#disabling-attribute-inheritance)
230- [Build Advanced Components in Vue 3 using $attrs](https://www.thisdot.co/blog/build-advanced-components-in-vue-3-using-usdattrs)
231