1---
2title: Component Fallthrough Attributes Best Practices
3impact: MEDIUM
4impactDescription: Incorrect $attrs access and reactivity assumptions can cause undefined values and watchers that never run
5type: best-practice
6tags: [vue3, attrs, fallthrough-attributes, composition-api, reactivity]
7---
8 
9# Component Fallthrough Attributes Best Practices
10 
11**Impact: MEDIUM** - Fallthrough attributes are straightforward once you follow Vue's conventions: hyphenated names use bracket notation, listener keys are camelCase `onX`, and `useAttrs()` is current-but-not-reactive.
12 
13## Task List
14 
15- Access hyphenated attribute names with bracket notation (for example `attrs['data-testid']`)
16- Access event listeners with camelCase `onX` keys (for example `attrs.onClick`)
17- Do not `watch()` values returned from `useAttrs()`; those watchers do not trigger on attr changes
18- Use `onUpdated()` for attr-driven side effects
19- Promote frequently observed attrs to props when reactive observation is required
20 
21## Access Attribute and Listener Keys Correctly
22 
23Hyphenated attribute names preserve their original casing in JavaScript, so dot notation does not work for keys that include `-`.
24 
25**BAD:**
26```vue
27<script setup>
28import { useAttrs } from 'vue'
29 
30const attrs = useAttrs()
31 
32console.log(attrs.data-testid)  // Syntax error
33console.log(attrs.dataTestid)   // undefined for data-testid
34console.log(attrs['on-click'])  // undefined
35console.log(attrs['@click'])    // undefined
36</script>
37```
38 
39**GOOD:**
40```vue
41<script setup>
42import { useAttrs } from 'vue'
43 
44const attrs = useAttrs()
45 
46console.log(attrs['data-testid'])
47console.log(attrs['aria-label'])
48console.log(attrs['foo-bar'])
49 
50console.log(attrs.onClick)
51console.log(attrs.onCustomEvent)
52console.log(attrs.onMouseEnter)
53</script>
54```
55 
56### Naming Reference
57 
58| Parent Usage | Access in `attrs` |
59|--------------|-------------------|
60| `class="foo"` | `attrs.class` |
61| `data-id="123"` | `attrs['data-id']` |
62| `aria-label="..."` | `attrs['aria-label']` |
63| `foo-bar="baz"` | `attrs['foo-bar']` |
64| `@click="fn"` | `attrs.onClick` |
65| `@custom-event="fn"` | `attrs.onCustomEvent` |
66| `@update:modelValue="fn"` | `attrs['onUpdate:modelValue']` |
67 
68## `useAttrs()` Is Not Reactive
69 
70`useAttrs()` always reflects the latest values, but it is intentionally not reactive for watcher tracking.
71 
72**BAD:**
73```vue
74<script setup>
75import { watch, watchEffect, useAttrs } from 'vue'
76 
77const attrs = useAttrs()
78 
79watch(
80  () => attrs.someAttr,
81  (newValue) => {
82    console.log('Changed:', newValue) // Never runs on attr changes
83  }
84)
85 
86watchEffect(() => {
87  console.log(attrs.class) // Runs on setup, not on attr updates
88})
89</script>
90```
91 
92**GOOD:**
93```vue
94<script setup>
95import { onUpdated, useAttrs } from 'vue'
96 
97const attrs = useAttrs()
98 
99onUpdated(() => {
100  console.log('Latest attrs:', attrs)
101})
102</script>
103```
104 
105**GOOD:**
106```vue
107<script setup>
108import { watch } from 'vue'
109 
110const props = defineProps({
111  someAttr: String
112})
113 
114watch(
115  () => props.someAttr,
116  (newValue) => {
117    console.log('Changed:', newValue)
118  }
119)
120</script>
121```
122 
123## Common Patterns
124 
125### Check for optional attrs safely
126 
127```vue
128<script setup>
129import { computed, useAttrs } from 'vue'
130 
131const attrs = useAttrs()
132 
133const hasTestId = computed(() => 'data-testid' in attrs)
134const ariaLabel = computed(() => attrs['aria-label'] ?? 'Default label')
135</script>
136```
137 
138### Forward listeners after internal logic
139 
140```vue
141<script setup>
142import { useAttrs } from 'vue'
143 
144defineOptions({ inheritAttrs: false })
145 
146const attrs = useAttrs()
147 
148function handleClick(event) {
149  console.log('Internal handling first')
150  attrs.onClick?.(event)
151}
152</script>
153 
154<template>
155  <button @click="handleClick">
156    <slot />
157  </button>
158</template>
159```
160 
161## TypeScript Notes
162 
163`useAttrs()` is typed as `Record<string, unknown>`, so cast individual keys when needed.
164 
165```vue
166<script setup lang="ts">
167import { useAttrs } from 'vue'
168 
169const attrs = useAttrs()
170 
171const testId = attrs['data-testid'] as string | undefined
172const onClick = attrs.onClick as ((event: MouseEvent) => void) | undefined
173</script>
174```
175