Lifecycle and Template Refs
By Syncfusion®, Inc. · Last updated
The life of a component from creation to mount, update and unmount, the Composition API lifecycle hooks with an Options API mapping, template refs with useTemplateRef(), refs inside v-for, component refs and defineExpose(), and common uses: DOM access, listeners, timers, requests and cleanup.
The Life of a Component
- A component is born, shown, updated and finally removed.
- These stages are its lifecycle.
- Lifecycle hook = a function Vue calls at one stage, such as "just shown".
- You use hooks to start and stop work that lives outside Vue: timers, listeners and requests.
Simple lesson: hooks let you run code when a component appears, changes or leaves.
A Real-World Example
- Meera's kitchen screen shows how long an order has been waiting.
- The timer must start when the order card appears.
- When the order is served, the card goes away. The timer must stop too.
- What happened:
onMountedstarted the timer once the card was on the page. - "Serve the order" removed the card.
onUnmountedstopped the timer.
What You Will Learn
- The four stages of a component's life.
- The Composition API hooks, and their Options API names.
- When each hook runs.
- How to reach a DOM element with a template ref.
- How to collect refs inside
v-for. - How to call a child component's functions.
- How
defineExpose()decides what a parent may use. - Common jobs for hooks, and how to clean up.
Lifecycle Stages
Animation: a dot moves along the lifecycle. Setup, before mount, mounted, then a loop of before update and updated, then before unmount and unmounted
setup onBeforeMount onMounted onBeforeUpdate onUpdated onBeforeUnmount onUnmounted
state changes: repeat
Created → shown → updated (many times) → removed
A component is set up, mounted, updated many times, then unmounted.
- Setup =
<script setup>runs. State is created. Nothing is on the page yet. - Mount = Vue builds the elements and puts them on the page.
- Update = state changed, so Vue updates the page.
- Unmount = the component is removed, for example by
v-if.
- What happened: the Console shows steps 1 to 3 at the start.
- Each like shows 4 and 5. "Remove" shows 6 and 7.
Hooks in the Options API
- Older code uses the Options API names. You will learn that style in Options API.
| Composition API | Options API | Runs |
|---|---|---|
<script setup> itself | beforeCreate, created | Before anything is on the page |
onBeforeMount | beforeMount | Just before the first render |
onMounted | mounted | After the elements are on the page |
onBeforeUpdate | beforeUpdate | Before the page is updated |
onUpdated | updated | After the page is updated |
onBeforeUnmount | beforeUnmount | Before removal |
onUnmounted | unmounted | After removal |
Call hooks at the top level of <script setup>, never later inside a setTimeout or after an await. Vue must know which component a hook belongs to when it is registered.
Simple lesson: onMounted to start, onUnmounted to clean up.
Template Refs
- Sometimes you need the real DOM element: to focus a box, measure a size or call a browser API.
- Give the element a
ref="name"attribute. - In the script,
useTemplateRef("name")(Vue 3.5) gives you a ref to it. - It is
nulluntil the component is mounted. Use it inonMountedor later. - Code written before Vue 3.5 uses
const box = ref(null)with the same name asref="box". It does the same job.
Before Vue 3.5, code used a plain ref with the same name: const searchBox = ref(null) with ref="searchBox". You will still see this in older projects. It works the same way.
Refs Inside v-for
- A
refinsidev-forgives an array of elements. - The order of the array may not match the order of the list. Use it for counting or looping, not by position.
Component Refs and defineExpose()
- A
refon a component gives you that component's instance. - With
<script setup>, a component is closed by default. The parent sees nothing inside. - The child chooses what to share with
defineExpose({ ... }). - Use this rarely. Props and events are usually the better way.
- What happened: the parent called
reset()and readplates. secretwas not exposed, so the parent cannot see it.
Simple lesson: ref + useTemplateRef() reach elements and components. defineExpose() decides what a child shares.
Common Jobs for Hooks
| Job | Start in | Clean up in |
|---|---|---|
| Focus or measure an element | onMounted | Nothing |
Listen to window or document | onMounted | onUnmounted (remove the listener) |
Timers: setInterval, setTimeout | onMounted | onUnmounted (clear it) |
| Load data from a server | onMounted or <script setup> | onUnmounted (abort the request) |
| A third-party chart or map | onMounted | onUnmounted (destroy it) |
Close the panel quickly, before the dishes load. The Console shows "Request cancelled", because onUnmounted aborted it.
Simple lesson: whatever you start in a hook, stop in onUnmounted.
TL;DR
- Lifecycle = setup → mount → update (many times) → unmount.
onMounted= the elements are on the page. Start DOM work, timers, listeners.onUpdated= the page shows the new state.onUnmounted= clean up timers, listeners and requests.- Options names =
mounted,updated,unmounted... - Template ref =
ref="name"+useTemplateRef("name"). - Refs in
v-for= an array of elements. - Component ref = the child's instance. Closed by default.
defineExpose()= what a child shares with a parent's ref.
Common mistakes
| Mistake | Wrong idea | Correct idea | What goes wrong |
|---|---|---|---|
| Using a template ref in setup | The element exists at once | Use it in onMounted or later | It is null |
| No cleanup for timers | Vue stops them | clearInterval in onUnmounted | Timers keep running after the component is gone |
Hook after await | Hooks work anywhere | Register hooks at the top level | A warning, and the hook never runs |
Changing state in onUpdated | It is a good place to fix values | Use computed or a watcher | An endless update loop |
Reading a child's state without defineExpose | Parents see everything | Expose what is needed | The value is undefined |
Refs in v-for by position | The order matches the list | Use them as an unordered set | The wrong element is changed |
Check Yourself
Exercises
What to Remember
- Components go through setup, mount, update and unmount.
- Start DOM work in
onMounted. Clean everything up inonUnmounted. - Register hooks at the top level of
<script setup>. ref="name"+useTemplateRef("name")reaches elements after mount.- Component refs see only what
defineExpose()shares.
Next: Options API