charging-cabinet/software/h5-uniapp/.agents/skills/vue-best-practices/reference/component-ref-requires-defineexpose.md

title, impact, impactDescription, type, tags

title	impact	impactDescription	type	tags
Component Refs Require defineExpose with Script Setup	HIGH	Parent components cannot access child ref properties unless explicitly exposed	gotcha	vue3 template-refs script-setup defineExpose component-communication

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. -->

Reference

• Vue.js Component Refs
• Script Setup - defineExpose