1---
2title: Component Refs Require defineExpose with Script Setup
3impact: HIGH
4impactDescription: Parent components cannot access child ref properties unless explicitly exposed
5type: gotcha
6tags: [vue3, template-refs, script-setup, defineExpose, component-communication]
7---
8 
9# Component Refs Require defineExpose with Script Setup
10 
11**Impact: HIGH** - Components using `<script setup>` are private by default. A parent component using a template ref to access a child will get an empty object unless the child explicitly exposes properties using `defineExpose()`. This is a fundamental change from Options API behavior.
12 
13This catches many developers off-guard when migrating from Options API, where `this.$refs.child` gave full access to the child instance.
14 
15## Task Checklist
16 
17- [ ] Use `defineExpose()` to explicitly expose properties/methods to parent refs
18- [ ] Only expose what's necessary - keep component internals private
19- [ ] Document exposed APIs as they form your component's public interface
20- [ ] Prefer props/emit for parent-child communication; use refs sparingly
21- [ ] Call defineExpose before any await operation (see async caveat)
22 
23**Incorrect:**
24```vue
25<!-- ChildComponent.vue -->
26<script setup>
27import { ref } from 'vue'
28 
29const count = ref(0)
30const internalState = ref('private')
31 
32function increment() {
33  count.value++
34}
35 
36function reset() {
37  count.value = 0
38}
39 
40// WRONG: Nothing exposed - parent ref sees empty object
41</script>
42 
43<template>
44  <div>{{ count }}</div>
45</template>
46```
47 
48```vue
49<!-- ParentComponent.vue -->
50<script setup>
51import { ref, onMounted } from 'vue'
52import ChildComponent from './ChildComponent.vue'
53 
54const childRef = ref(null)
55 
56onMounted(() => {
57  // WRONG: childRef.value is {} - empty object!
58  console.log(childRef.value.count) // undefined
59  childRef.value.increment() // TypeError: not a function
60})
61</script>
62 
63<template>
64  <ChildComponent ref="childRef" />
65</template>
66```
67 
68**Correct:**
69```vue
70<!-- ChildComponent.vue -->
71<script setup>
72import { ref } from 'vue'
73 
74const count = ref(0)
75const internalState = ref('private') // Keep this private
76 
77function increment() {
78  count.value++
79}
80 
81function reset() {
82  count.value = 0
83}
84 
85// CORRECT: Explicitly expose public API
86defineExpose({
87  count,      // Expose the ref
88  increment,  // Expose methods
89  reset
90  // internalState NOT exposed - stays private
91})
92</script>
93 
94<template>
95  <div>{{ count }}</div>
96</template>
97```
98 
99```vue
100<!-- ParentComponent.vue -->
101<script setup>
102import { ref, onMounted } from 'vue'
103import ChildComponent from './ChildComponent.vue'
104 
105const childRef = ref(null)
106 
107onMounted(() => {
108  // CORRECT: Can access exposed properties
109  console.log(childRef.value.count) // 0
110  childRef.value.increment() // Works!
111 
112  // internalState is not accessible (private)
113  console.log(childRef.value.internalState) // undefined
114})
115</script>
116 
117<template>
118  <ChildComponent ref="childRef" />
119</template>
120```
121 
122```vue
123<!-- Input wrapper example - exposing native element -->
124<script setup>
125import { ref } from 'vue'
126 
127const inputEl = ref(null)
128 
129// Expose the native input for parent to access (e.g., for focus)
130defineExpose({
131  focus: () => inputEl.value?.focus(),
132  blur: () => inputEl.value?.blur(),
133  // Or expose the element directly
134  el: inputEl
135})
136</script>
137 
138<template>
139  <input ref="inputEl" v-bind="$attrs" />
140</template>
141```
142 
143```javascript
144// Options API equivalent using expose option
145export default {
146  expose: ['count', 'increment', 'reset'],
147  data() {
148    return {
149      count: 0,
150      internalState: 'private'
151    }
152  },
153  methods: {
154    increment() { this.count++ },
155    reset() { this.count = 0 }
156  }
157}
158```
159 
160## Best Practice Reminder
161 
162Component refs create tight coupling between parent and child. Prefer standard patterns:
163 
164```vue
165<!-- PREFERRED: Use props and emit for communication -->
166<script setup>
167const props = defineProps(['modelValue'])
168const emit = defineEmits(['update:modelValue'])
169</script>
170 
171<!-- Only use refs for imperative actions like focus(), scrollTo(), etc. -->
172```
173 
174## Reference
175- [Vue.js Component Refs](https://vuejs.org/guide/essentials/template-refs.html#ref-on-component)
176- [Script Setup - defineExpose](https://vuejs.org/api/sfc-script-setup.html#defineexpose)
177