Component Refs Require defineExpose with Script Setup
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.
This catches many developers off-guard when migrating from Options API, where this.$refs.child gave full access to the child instance.
Task Checklist
- Use
defineExpose()to explicitly expose properties/methods to parent refs - Only expose what's necessary - keep component internals private
- Document exposed APIs as they form your component's public interface
- Prefer props/emit for parent-child communication; use refs sparingly
- Call defineExpose before any await operation (see async caveat)
Incorrect:
<!-- ChildComponent.vue -->
<script setup>
import { ref } from 'vue'
const count = ref(0)
const internalState = ref('private')
function increment() {
count.value++
}
function reset() {
count.value = 0
}
// WRONG: Nothing exposed - parent ref sees empty object
</script>
<template>
<div>{{ count }}</div>
</template><!-- ParentComponent.vue -->
<script setup>
import { ref, onMounted } from 'vue'
import ChildComponent from './ChildComponent.vue'
const childRef = ref(null)
onMounted(() => {
// WRONG: childRef.value is {} - empty object!
console.log(childRef.value.count) // undefined
childRef.value.increment() // TypeError: not a function
})
</script>
<template>
<ChildComponent ref="childRef" />
</template>Correct:
<!-- ChildComponent.vue -->
<script setup>
import { ref } from 'vue'
const count = ref(0)
const internalState = ref('private') // Keep this private
function increment() {
count.value++
}
function reset() {
count.value = 0
}
// CORRECT: Explicitly expose public API
defineExpose({
count, // Expose the ref
increment, // Expose methods
reset
// internalState NOT exposed - stays private
})
</script>
<template>
<div>{{ count }}</div>
</template><!-- ParentComponent.vue -->
<script setup>
import { ref, onMounted } from 'vue'
import ChildComponent from './ChildComponent.vue'
const childRef = ref(null)
onMounted(() => {
// CORRECT: Can access exposed properties
console.log(childRef.value.count) // 0
childRef.value.increment() // Works!
// internalState is not accessible (private)
console.log(childRef.value.internalState) // undefined
})
</script>
<template>
<ChildComponent ref="childRef" />
</template><!-- Input wrapper example - exposing native element -->
<script setup>
import { ref } from 'vue'
const inputEl = ref(null)
// Expose the native input for parent to access (e.g., for focus)
defineExpose({
focus: () => inputEl.value?.focus(),
blur: () => inputEl.value?.blur(),
// Or expose the element directly
el: inputEl
})
</script>
<template>
<input ref="inputEl" v-bind="$attrs" />
</template>// Options API equivalent using expose option
export default {
expose: ['count', 'increment', 'reset'],
data() {
return {
count: 0,
internalState: 'private'
}
},
methods: {
increment() { this.count++ },
reset() { this.count = 0 }
}
}Best Practice Reminder
Component refs create tight coupling between parent and child. Prefer standard patterns:
<!-- PREFERRED: Use props and emit for communication -->
<script setup>
const props = defineProps(['modelValue'])
const emit = defineEmits(['update:modelValue'])
</script>
<!-- Only use refs for imperative actions like focus(), scrollTo(), etc. -->