1---
2title: Locally Registered Components Are Not Available in Descendants
3impact: HIGH
4impactDescription: Common source of "component not found" errors in nested components
5type: gotcha
6tags: [vue3, component-registration, local-registration, scope, nested-components]
7---
8 
9# Locally Registered Components Are Not Available in Descendants
10 
11**Impact: HIGH** - Locally registered components are only available in the component where they are registered, NOT in its child or descendant components. This is a common source of "Unknown component" or "Failed to resolve component" errors when developers expect a component registered in a parent to be available in children.
12 
13## Task Checklist
14 
15- [ ] Import and register components in every file where they are used
16- [ ] Do not expect parent's local components to be available in children
17- [ ] If a component is needed in many places, consider global registration only as a last resort
18- [ ] Use IDE auto-import features to simplify repeated imports
19 
20**Incorrect:**
21```vue
22<!-- ParentComponent.vue -->
23<script setup>
24import Card from './Card.vue'
25import ChildComponent from './ChildComponent.vue'
26</script>
27 
28<template>
29  <Card>Parent content</Card>
30  <ChildComponent />
31</template>
32```
33 
34```vue
35<!-- ChildComponent.vue -->
36<script setup>
37// WRONG: Expecting Card to be available because parent imported it
38// This will cause "Failed to resolve component: Card" error
39</script>
40 
41<template>
42  <!-- ERROR: Card is not available here! -->
43  <Card>
44    Child content
45  </Card>
46</template>
47```
48 
49**Correct:**
50```vue
51<!-- ParentComponent.vue -->
52<script setup>
53import Card from './Card.vue'
54import ChildComponent from './ChildComponent.vue'
55</script>
56 
57<template>
58  <Card>Parent content</Card>
59  <ChildComponent />
60</template>
61```
62 
63```vue
64<!-- ChildComponent.vue -->
65<script setup>
66// CORRECT: Each component must import what it uses
67import Card from './Card.vue'
68</script>
69 
70<template>
71  <Card>
72    Child content
73  </Card>
74</template>
75```
76 
77## Common Scenarios
78 
79### Scenario 1: Deeply Nested Components
80```vue
81<!-- GrandchildComponent.vue -->
82<script setup>
83// Even if parent and grandparent both use Card,
84// grandchild must import it separately
85import Card from '@/components/Card.vue'
86import Button from '@/components/Button.vue'
87</script>
88 
89<template>
90  <Card>
91    <Button>Click me</Button>
92  </Card>
93</template>
94```
95 
96### Scenario 2: Slot Content with Components
97```vue
98<!-- Parent.vue -->
99<script setup>
100import Modal from './Modal.vue'
101import Form from './Form.vue'
102</script>
103 
104<template>
105  <!-- Form is registered in Parent, so it works in slot content -->
106  <Modal>
107    <Form /> <!-- This works because slot content is compiled in Parent's scope -->
108  </Modal>
109</template>
110```
111 
112```vue
113<!-- Modal.vue -->
114<script setup>
115// Modal doesn't need to import Form because slot content
116// is compiled in the parent's scope, not Modal's scope
117</script>
118 
119<template>
120  <div class="modal">
121    <slot /> <!-- Form component works here because it's parent's slot content -->
122  </div>
123</template>
124```
125 
126### Scenario 3: Dynamic Components
127```vue
128<!-- Container.vue -->
129<script setup>
130import TabA from './TabA.vue'
131import TabB from './TabB.vue'
132import { ref, shallowRef } from 'vue'
133 
134// When using dynamic components, all possible components must be imported
135const currentTab = shallowRef(TabA)
136</script>
137 
138<template>
139  <component :is="currentTab" />
140</template>
141```
142 
143## Why This Design?
144 
145Local registration provides:
1461. **Explicit dependencies** - You can see exactly what each component uses
1472. **Tree-shaking** - Unused components are removed from bundles
1483. **Clear scope** - No magic or implicit behavior
149 
150## Reference
151- [Vue.js Component Registration - Local Registration](https://vuejs.org/guide/components/registration.html#local-registration)
152