DEV Community: Izak T

Perry Mason in: The Case of the Drifting Timer

Izak T — Thu, 13 Aug 2026 15:17:42 +0000

Perry Mason in: The Case of the Drifting Timer

Opening Statement

You need a reactive "current time" in your Vue 3 app. A schedule grid with a red
line showing "now." A live clock. A dashboard that updates every minute.

Every Vue developer reaches for setInterval first. It works. But "works" and
"works well" are different things.

This is the story of taking a naive timer from "it ticks" to production-grade —
and the four iterations it took to get there. The prosecution calls four
exhibits. Let's begin.

Exhibit A: The Memory Leak

const currentTime = ref(new Date())

onMounted(() => {
  setInterval(() => {
    currentTime.value = new Date()
  }, 60000)
})

It works. Sort of. The defense rests — but the prosecution is just getting
started.

Exhibits of negligence:

The interval is never cleared. When the component unmounts, the timer keeps firing every 60 seconds forever — updating a ref nothing reads anymore, and holding its closure (and everything the ref references) in memory for the lifetime of the page.
Silent. Invisible. The kind of leak that shows up in production after a user navigates around your app for 20 minutes.

Exhibit B: The Cleanup That Failed

const currentTime = ref(new Date())
let timeInterval = null

onMounted(() => {
  currentTime.value = new Date()
  timeInterval = setInterval(() => {
    currentTime.value = new Date()
  }, 60000)
})

onUnmounted(() => {
  if (timeInterval) clearInterval(timeInterval)
})

Now we clean up. The interval is stored in a variable, cleared on unmount.
A step forward — but the prosecution has three more objections:

Further evidence:

This only works inside components. If someone calls this logic from a Pinia store or outside a component's setup() context, onUnmounted never fires. The timer leaks silently. (Composables called synchronously during setup() are fine — Vue's docs recommend exactly that. The problem is when there's no component instance at all.)
The timer fires 60 seconds after load, not at the top of the minute. If a user opens your app at 10:00:58, the clock won't update until 10:01:58. Your app looks broken — the system tray says 10:01 but your UI still shows 10:00.
The timer keeps running when the tab is hidden. Wasting CPU on a clock nobody is looking at.

Exhibit C: Scope-Safe Cleanup

Vue 3.2 introduced onScopeDispose — proposed in
RFC #0041: Reactivity Effect Scope
and shipped in Vue 3.2 (August 2021).
The RFC describes it as:

The global hook onScopeDispose() serves a similar functionality to
onUnmounted(), but works for the current scope instead of the component
instance. This could benefit composable functions to clean up their side
effects along with its scope. Since setup() also creates a scope for the
component, it will be equivalent to onUnmounted() when there is no explicit
effect scope created.

— Vue RFC #0041, "Reactivity Effect Scope"

That's not marketing — the implementation really is just a push onto the
currently active scope's cleanup list. From the Vue core source
(packages/reactivity/src/effectScope.ts):

function onScopeDispose(fn, failSilently = false) {
  if (activeEffectScope) {
    activeEffectScope.cleanups.push(fn)
  } else if (!failSilently) {
    warn(`onScopeDispose() is called when there is no active effect scope to be associated with.`)
  }
}

"Currently active" is the key phrase. Every component's setup() runs inside an
effect scope that Vue creates and activates for you — before invoking your setup
code, setupComponent routes through setCurrentInstance, which calls
instance.scope.on() — so inside a component the cleanup is automatic. The RFC's
own example makes the guarantee explicit:

This still works because a Vue component now also runs its setup() inside a
scope, which will be disposed when the component is unmounted.

— Vue RFC #0041, "Reactivity Effect Scope"

onScopeDispose() cleans up automatically when useNow() is called
synchronously within an active Vue effect scope — such as component setup or
setup-store creation. Outside one, callers must retain and call the returned
stop() or create their own scope.

// In a component — Vue creates the scope, onScopeDispose just works
const { now: currentTime } = useNow()

Pinia setup stores also run inside their own effect scope. The
Pinia $dispose() docs
confirm: calling store.$dispose() stops the store's associated effect scope,
which triggers any onScopeDispose callbacks registered during setup. Note that
unlike component unmount, $dispose() must be called intentionally — it is not
automatic.

The only time you reach for effectScope() yourself is when there's genuinely
no scope to hook into — app-level singletons, plugins, plain modules. In
that case, either create a scope and remember to stop it:

// No component, no store — create a scope, and remember to stop it
const scope = effectScope()
scope.run(() => {
  const { now: currentTime } = useNow()
})
scope.stop() // triggers cleanup

…or skip the scope and call stop() manually:

// No scope at all — caller disposes manually
const { now: currentTime, stop } = useNow()
// ...later, when the owner is torn down:
stop()

One caveat, straight from the
Vue docs:
if onScopeDispose is called with no active scope, Vue logs a warning and
the callback is never registered. Vue 3.5+ accepts a second argument,
onScopeDispose(cleanup, true), which suppresses the warning — but the
callback is still not registered. That's why the final composable uses
failSilently = true and exposes stop() for manual disposal.

Exhibit D: Clock Alignment + Visibility Pause

The final version addresses the human-perception problem and the battery-drain
problem.

Clock Alignment

If you load at 10:00:58, you don't want to wait 60 seconds for the first tick.
You want the clock to update at 10:01:00 — aligned to the next interval
boundary (minute boundaries with the default 60,000 ms interval).

const msUntilNextTick = interval - (Date.now() % interval)
setTimeout(() => {
  now.value = Temporal.Now.plainTimeISO()
  timer = setInterval(() => {
    now.value = Temporal.Now.plainTimeISO()
  }, interval)
}, msUntilNextTick)

The initial setTimeout fires at the next interval boundary, then hands off to
a recurring timer for all subsequent ticks. The clock feels synchronized with
the system tray.

But there's a subtlety: setInterval drifts. Modern browsers under system
load or low-power modes can slip a few milliseconds per tick. Over hours, the
timer ends up firing 5–10 seconds past the top of the minute. The fix is a
self-correcting recursive setTimeout that recalculates
interval - (Date.now() % interval) on every tick — re-aligning to the
real interval boundary each time. Delay does not accumulate from one tick to
the next — if the browser runs a callback late, the next callback is scheduled
toward the next clock boundary rather than inheriting the previous lateness.

Visibility Pause

When the user switches tabs, document.hidden becomes true. We stop the
timer. When they come back, we immediately sync the time and restart the
interval.

const onVisibilityChange = () => {
  if (document.hidden) {
    stop()
  } else {
    start() // immediately reads the current time, then starts ticking
  }
}

No wasted CPU when nobody is looking. No stale time when they return.

SSR Safety

If this composable runs during Server-Side Rendering (Nuxt, Vite SSG),
document doesn't exist. Calling document.addEventListener at the top level
would crash with ReferenceError: document is not defined.

The fix: wrap all DOM-dependent code in a typeof window !== 'undefined'
guard. The DOM code is SSR-safe. To make the composable fully SSR-safe, the
server and target browsers must also provide Temporal, either natively or
through an explicitly imported polyfill.

Hydration note: Rendering live time on the server can cause hydration
mismatches because the server and browser render at different moments — and
potentially in different time zones. The cleanest pattern for a live clock is
to render a neutral placeholder server-side and start the actual clock after
client mount.

Temporal Precision

Temporal.Now.plainTimeISO() defaults to nanosecond precision
(e.g., 14:30:15.123456789). When bound directly to a template, those
sub-second digits render as noise. The fix: round to seconds with
.round({ smallestUnit: 'second' }) so now.value formats cleanly out of the
box.

The Verdict: The Final Composable

import { shallowRef, onScopeDispose } from 'vue'
// If Temporal isn't available natively (e.g. Safari), import a polyfill first:
// import { Temporal } from '@js-temporal/polyfill'

export function useNow(interval = 60000) {
  if (!Number.isFinite(interval) || interval <= 0) {
    throw new RangeError('interval must be a positive number of milliseconds')
  }

  // Round to seconds so default template rendering is clean (e.g., "14:30:15")
  const getNow = () =>
    Temporal.Now.plainTimeISO().round({ smallestUnit: 'second' })

  // shallowRef: Temporal.PlainTime is immutable — no need for Vue to proxy
  // its internals. We only ever replace .value, never mutate it.
  const now = shallowRef(getNow())
  let timer = null

  const stop = () => {
    if (timer !== null) {
      clearTimeout(timer)
      timer = null
    }
  }

  // Self-correcting recursive timeout: recalculates remaining ms to next
  // boundary on every tick — delay does not accumulate across ticks
  const scheduleNextTick = () => {
    stop()
    const msUntilNextTick = interval - (Date.now() % interval)
    timer = setTimeout(() => {
      now.value = getNow()
      scheduleNextTick()
    }, msUntilNextTick)
  }

  const start = () => {
    // Don't schedule if the page is already hidden (e.g. loaded in a
    // background tab) — visibilitychange only fires on state changes
    if (typeof document !== 'undefined' && document.hidden) return
    stop()
    now.value = getNow()
    scheduleNextTick()
  }

  const onVisibilityChange = () => {
    if (document.hidden) stop()
    else start()
  }

  const dispose = () => {
    stop()
    if (typeof document !== 'undefined') {
      document.removeEventListener('visibilitychange', onVisibilityChange)
    }
  }

  // SSR Safe: only attach DOM listeners in the browser environment
  if (typeof window !== 'undefined') {
    start()
    document.addEventListener('visibilitychange', onVisibilityChange)
  }

  // failSilently=true: if no active scope, caller must call stop() manually
  onScopeDispose(dispose, true)

  return { now, stop: dispose }
}

Usage in a component:

// Vue creates the scope — onScopeDispose handles cleanup automatically
const { now: currentTime } = useNow()

Usage outside a scope (plugins, plain modules):

// No active scope — caller disposes manually
const { now: currentTime, stop } = useNow()
// ...later, when the owner is torn down:
stop()

The composable handles:

Clock alignment to interval boundaries (minute boundaries with the default 60,000 ms interval; self-correcting, non-accumulating delay)
Tab visibility pausing (including when the page loads already hidden)
Scope-safe cleanup when called inside an active scope (components, Pinia setup stores, effectScope)
Manual disposal via stop() when called outside a scope
SSR safety for DOM code (Temporal must be available on the server too — import a polyfill if needed)
Clean Temporal formatting (rounded to seconds)
shallowRef for immutable Temporal objects (no unnecessary proxying)

Many clocks on one page? Each useNow() call creates its own timer and
visibilitychange listener. That's fine for one or a few clocks, but if a
page renders many clock components, consider sharing a single app-level
useNow() instance via effectScope() and passing the ref down via props or
provide/inject.

Closing Arguments: Why Recursive `setTimeout` Instead of `setInterval`?

setInterval: Fires on a fixed interval, but modern browsers drift under
load or in low-power modes. A few milliseconds per tick compounds over hours —
your clock ends up 5–10 seconds off the real interval boundary. Since we're
building a clock UI, that drift is visible to users.

setTimeout (recursive): Each callback recalculates
interval - (Date.now() % interval) before scheduling the next tick. This
re-aligns to the real interval boundary on every tick. Delay does not
accumulate — if the browser runs a callback late, the next callback targets
the next clock boundary rather than inheriting the previous lateness. The
callback reads Temporal.Now.plainTimeISO() — instantaneous — so there's no
risk of overlapping calls.

requestAnimationFrame: Fires ~60x/sec, synced to screen refresh. Designed
for smooth animations. Way too frequent for a 60-second clock.

nextTick: Not a timer at all. Fires once, after Vue's DOM update cycle. No
concept of time or repetition.

For a clock that needs to stay in sync with the system tray over long sessions,
self-correcting recursive setTimeout is the right tool. Browser timer
scheduling is not exact
— the event loop can be busy, and background tabs are commonly throttled — but
self-correction ensures that lateness doesn't compound.

Expert Testimony: Why Temporal API Instead of `Date`?

Date is perfectly reasonable for a simple display clock — especially if your
app doesn't already depend on Temporal. But if your app already uses Temporal
for its date/time semantics, it's the natural choice here.

The Date object is mutable — setHours(), setDate(), setMinutes() all
modify the instance in place. This leads to subtle bugs when the same instance
is shared across reactive state.

Temporal.PlainTime and Temporal.PlainDate are immutable. Every operation
returns a new instance. No mutation bugs possible. PlainTime represents
wall-clock time without a date or time zone — exactly what a display clock
needs.

// Date — mutable, error-prone
const d = new Date()
d.setHours(0, 0, 0, 0) // mutates d in place

// Temporal — immutable, safe
const today = Temporal.Now.plainDateISO() // no time component to zero out
const tomorrow = today.add({ days: 1 }) // returns new instance, today unchanged

Temporal's status, per the
official TC39 proposal:

This proposal is currently Stage 4. It will be merged into the ECMA-262 and
ECMA-402 standards and this repository will be archived.

— tc39/proposal-temporal

As of mid-2026 it's formally standardized as Stage 4 and being merged into the
ES2027 specification (the TC39
finished-proposals list updated the target publication year from 2026 to 2027).
It's available in current Chromium and Firefox, but production cross-browser
support still requires a fallback or polyfill — Safari and iOS Safari remain
unsupported. The proposal's implementation status and
caniuse agree:

Chrome 144+ — shipped January 13, 2026
Firefox 139+ — shipped May 27, 2025
Edge 144+ — Chromium-aligned
Safari — Technology Preview only, disabled by default; the WebKit implementation bug is still open
Node.js 26+ — shipped May 5, 2026

If you need to support browsers without native Temporal, drop in a polyfill such
as @js-temporal/polyfill
or temporal-polyfill.

Case Summary

"Works" is not "works well." The naive setInterval ticks. But it leaks,
drifts from real time, and wastes CPU on hidden tabs.
Prefer onScopeDispose for reusable composables. It works inside any
active Vue effect scope (components, Pinia setup stores, effectScope()) —
and inside components it's literally equivalent to onUnmounted, per RFC

0041. But it's not magic: if there's no active scope, the callback is never

registered. Always expose a manual stop() for unmanaged usage.
Clock alignment is a human-perception problem. Users don't know what
"drift" means, but they know your clock looks wrong when it doesn't match
their system tray.
Self-correcting beats fixed intervals. setInterval drifts under load.
A recursive setTimeout that recalculates alignment on every tick ensures
delay doesn't accumulate — the next tick always targets the next real clock
boundary.
Guard against SSR. If your composable touches document or window,
wrap it in typeof window !== 'undefined'. And if you use Temporal, make
sure the server has it too — natively or via polyfill.
Use shallowRef for immutable objects. Temporal.PlainTime is
immutable — you only ever replace .value, never mutate its internals.
shallowRef avoids unnecessary proxy conversion and is the appropriate
model for external class instances.

The court finds setInterval guilty of negligence. The composable is released
into production. Case closed. ⚖️

The Case of the Lying Clock: 5 Vue Mysteries Solved

Izak T — Thu, 13 Aug 2026 03:34:40 +0000

Every detective has their cold cases. These are mine — five Vue concepts that
confused me until I investigated them properly. Grab your magnifying glass.

Case #1: The Lying Clock

Imagine you set an alarm to go off every 60 seconds. You press start at
10:00:00.

First alarm: 10:01:00 — perfect
Second alarm: 10:02:00 — still good
But your phone is also doing other things: checking email, refreshing weather, running background tasks. Sometimes it fires the alarm a tiny bit late.
Third alarm: 10:03:01 (1 second late)
Fourth alarm: 10:04:02 (2 seconds off now)
Five hours later: your alarm fires at 15:05:12 when it should fire at 15:05:00

That gap growing bigger over time — that's drift. The timer slowly slides
away from where it should be.

Why Does This Happen?

JavaScript runs on a single thread — it can only do one thing at a time. When a
timer is supposed to fire, the browser puts it in a queue. But if the thread is
busy doing something else, the timer waits. The MDN documentation for
setTimeout
lists several reasons timers fire late:

Nested timeouts are throttled to a minimum of 4ms after 5 levels of nesting (per the HTML5 spec)
Background tabs are throttled to a maximum of once per second (MDN: "timeouts are throttled to firing no more often than once per second (1000 ms) in inactive tabs")
Chrome 88+ introduced intensive throttling for hidden pages: timers that have been hidden for more than 5 minutes are checked only once per minute
Tracking scripts in Firefox get even more aggressive throttling: 10 second minimum in background tabs

Does This Happen on New Devices Too?

Yes, but less. Modern devices are faster, so the delay per tick is smaller —
maybe 1-2 milliseconds instead of 10-20. But over hours, even 1ms per tick
adds up. And background tab throttling happens on every device, no matter how
fast — it's a browser policy, not a hardware limitation.

Is This Common Knowledge?

It's the kind of thing you learn when your boss says "why does the clock on
our dashboard show the wrong time after lunch?" and you Google it. Many
developers use setInterval and never notice because their app doesn't stay
open long enough for the drift to matter.

Case #1 Continued: How Recursive `setTimeout` Fixes the Drift

A fixed interval can fall behind its intended clock boundary when callbacks
run late — the lateness piles up:

Start at 10:00:00
→ fire at 10:01:00.002 (2ms late)
→ fire at 10:02:00.005 (5ms late)
→ fire at 10:03:00.009 (getting worse)
→ ...hours later, you're 10+ seconds off

Recursive setTimeout recalculates the next boundary from wall-clock time
each tick, so delay doesn't accumulate:

Start at 10:00:00
→ "next minute is 10:01:00, that's 60000ms away" → set timeout for 60000ms
→ fire at 10:01:00.002 (2ms late — same as before)
→ BUT NOW: check clock: "it's 10:01:00.002, next minute is 10:02:00, that's 59998ms"
→ set timeout for 59998ms
→ fire at 10:02:00.001 (only 1ms late! it corrected itself!)
→ check clock: "it's 10:02:00.001, next minute is 10:03:00, that's 59999ms"
→ fire at 10:03:00.000 — right on time

It's called "recursive" because the function calls itself — inside the
setTimeout callback, we call scheduleNextTick() again, which sets up the
next setTimeout. It's a loop that builds itself one step at a time.

Analogy:

setInterval = a runner who counts their steps and hopes they're on pace
Recursive setTimeout = a runner who checks their watch before every step

Case #2: The Box That Didn't Need Tracking — `shallowRef` vs `ref`

When you put an object inside ref(), Vue wraps every single property in a
reactive proxy. If your object has { hour: 14, minute: 30, second: 15 }, Vue
tracks all three properties — plus every method, plus any nested objects. This
is great when you need to change one property and have the UI update.

But Temporal.PlainTime is immutable — you can never change its properties.
You can only throw the whole thing away and make a new one. So Vue's deep
tracking is wasted effort.

shallowRef says: "only track .value itself, don't go inside." The Vue
documentation puts
it plainly:

Unlike ref(), the inner value of a shallow ref is stored and exposed as-is,
and will not be made deeply reactive. Only the .value access is reactive.

And the docs even tell you when to use it:

shallowRef() is typically used for performance optimizations of large data
structures, or integration with external state management systems.

Since we only ever do now.value = getNow() (replace the whole object) and
never mutate internal properties, shallowRef does exactly what we need — and
nothing we don't.

Analogy: ref is like putting a GPS tracker on every item inside a box.
shallowRef is like putting a tracker only on the box. If you never open the
box and change items inside — you only swap the whole box — the single tracker
is enough.

Case #3: The Cleanup That Worked Everywhere — Effect Scopes and `onScopeDispose`

The Problem

When a component unmounts, Vue needs to clean up — stop timers, remove event
listeners, cancel watchers. onUnmounted is the hook for this. But it only
works inside components. If you use a composable from a Pinia store or a
standalone module, onUnmounted never fires — there's no component to unmount.

The Solution

Vue 3.2 introduced effectScope and onScopeDispose via
RFC #0041.
The RFC explains the motivation:

In Vue's component setup(), effects will be collected and bound to the
current instance. When the instance gets unmounted, effects will be disposed
automatically. This RFC is trying to abstract the component's setup()
effect collecting and disposing feature into a more reusable API that can be
used outside of the component model.

In plain English: Vue already had this cleanup mechanism inside components. They
just made it available outside components too.

How It Works

Every component's setup() runs inside an effect scope — Vue creates it
automatically. onScopeDispose registers a cleanup callback on whatever scope
is currently active. The Vue docs
describe it as:

Registers a dispose callback on the current active effect scope. This method
can be used as a non-component-coupled replacement of onUnmounted in
reusable composition functions, since each Vue component's setup() function
is also invoked in an effect scope.

So inside a component, onScopeDispose and onUnmounted do the same thing.
But onScopeDispose also works in Pinia stores and standalone scopes.

Will `onMounted` and `onUnmounted` Go Away?

onMounted — stays forever. It's about the DOM being ready, not about cleanup. Neither effectScope nor onScopeDispose can replace it.
onUnmounted — mostly replaced by onScopeDispose for cleanup in composables. It still works, but onScopeDispose is more versatile.

What Happens If You Use Both Inside a Component?

Nothing bad — they both fire during teardown. No conflict, no error.
It's just redundant — using both for the same cleanup is unnecessary.

The Catch: No Active Scope

If onScopeDispose is called with no active scope (like from a plain module),
Vue logs a warning and the callback is never registered. The
Vue source
shows exactly why:

function onScopeDispose(fn, failSilently = false) {
  if (activeEffectScope) {
    activeEffectScope.cleanups.push(fn)
  } else if (!failSilently) {
    warn(`onScopeDispose() is called when there is no active effect scope...`)
  }
}

No activeEffectScope → no push → no cleanup. That's why our composable uses
failSilently = true (to suppress the warning) and exposes a stop()
function (so the caller can clean up manually).

Analogy: onUnmounted is like "tell me when the building is demolished."
onScopeDispose is like "tell me when my room is demolished" — works whether
your room is in a building, a store, or a standalone structure. But if you're
not in any room at all, nobody will tell you anything — so keep a fire
extinguisher (stop()) handy.

Case #4: The Server That Knew Too Much — Hydration

The Short Version

When using SSR (Server-Side Rendering, like Nuxt), the server generates complete
HTML and sends it to the browser. The user sees a full page immediately. Then
Vue loads in the browser and "takes over" that HTML — attaching event listeners,
making it interactive. That takeover is hydration.

Why It Matters for Clocks

The server renders at one moment — say 10:00:00. That HTML travels across the
internet for 500ms. The browser hydrates at 10:00:01. Vue compares the server
HTML to what it wants to render and finds a mismatch: the server wrote 10:00:00
but the browser wants 10:00:01.

The Nuxt hydration guide
lists this as a common problem:

Content that changes based on current time.

And Nazar Boyko's deep dive on hydration
explains why it matters:

The server runs this code at, say, 14:32:01. The client runs it at 14:32:03.
The text nodes do not match, and Vue complains.

It gets worse: the server might be in a different time zone than the user. A
server in New York rendering 10:00:00 EST is 15:00:00 for a user in Tokyo.

The Fix

The cleanest pattern is to render a placeholder on the server and start the real
clock only after the browser takes over. As the
Mastering Nuxt guide
recommends:

Render time only on the client.

Or use Nuxt's <ClientOnly>
component, or the
<NuxtTime> component which is
specifically designed for SSR-safe time rendering.

Analogy: It's like a restaurant menu printed yesterday with "Today's Special:
Soup." When you read it today, it's wrong. Better to leave the special blank on
the printed menu and write it in by hand when the customer sits down.

Does This Apply to Every Project?

No — if you're using plain Vite + Vue, not SSR, there's no hydration. But a
good composable handles it anyway with the typeof window !== 'undefined'
guard, which is good practice for reusable code that someone might use in Nuxt
someday.

Case #5: The Warning Nobody Needed — `failSilently`

When onScopeDispose is called with no active scope, Vue logs a warning:
"Hey, there's no scope to attach this to!" That warning can be noisy if you
intentionally call the composable outside a scope.

Passing true as the second argument tells Vue: "I know there might not be a
scope. Don't warn me. I'll handle cleanup myself with stop()."

Important: failSilently = true does not create cleanup. It just hides
the warning. The callback is still not registered. You still need stop().

Mini-note: Temporal Rounding — Temporal.Now.plainTimeISO() gives you
nanosecond precision (14:30:15.123456789). That's nine digits after the
seconds. .round({ smallestUnit: 'second' }) trims it to 14:30:15. Clean.
Like showing "$14.30" instead of "$14.300000001."

Case Closed

Timer drift — A fixed interval can fall behind its intended clock boundary; recursive setTimeout recalculates from wall-clock time each tick
shallowRef — Only tracks .value replacement, not internal property changes — perfect for immutable objects
Effect scopes + onScopeDispose — Scopes group reactive effects for disposal; onScopeDispose registers cleanup on the active scope — works in components, setup-store creation, and manual scopes, but not with no scope at all
Hydration — Server sends HTML, browser "takes over" — time-based content can mismatch between the two
failSilently — Suppresses the "no active scope" warning; does NOT create cleanup — you still need stop()

Stop Using Props + Watchers Just to Trigger Actions in Child Components (Vue 3.5 useTemplateRef + defineExpose)

Izak T — Fri, 07 Aug 2026 22:41:36 +0000

How many times have you seen (or written) code where a parent component passes a boolean prop to a child component solely to trigger a method inside that child?

<!-- ❌ Parent passing a trigger flag -->
<ChildComponent :shouldReset="isResetting"/>

Inside the child component, you end up writing an artificial watcher just to catch that state flip:

<!-- ❌ Child watching a prop just to run a method -->
<script setup>
import { watch } from 'vue'

const props = defineProps<{ shouldReset: boolean }>()

watch(() => props.shouldReset, (newVal) => {
  if (newVal) {
    resetForm() // Running internal logic based on prop change
  }
})
</script>

This is a classic Vue code smell. Passing state down when you actually mean to send a command creates awkward state-toggling hacks, extra reactivity cycles, and unnecessary watcher logic.

Here is how to clean up this anti-pattern using defineExpose and Vue 3.5’s useTemplateRef().

Why "Props + Watchers" as Action Triggers is a Smell

Artificial State Pollution: You have to manage boolean flags in the parent (isResetting = true, then back to false) just to fire a one-time event.
Reactivity Overhead: Vue has to track the prop dependency, queue the watcher, evaluate the callback, and schedule component re-renders—all to invoke a simple function.
Cluttered Child Logic: The child component needs boilerplate code to watch a prop, handle boolean states, and reset the flag.

Vue is primarily declarative, but UI actions are inherently imperative. Focusing an input, resetting a form, playing an animation, or stepping through a wizard are actions, not state.

The Better Pattern: `defineExpose` + `useTemplateRef`

Instead of forcing declarative props onto an imperative action, expose the child’s internal function directly to the parent.

Step 1: Explicitly Expose the Method in the Child

By default, components using <script setup> are closed. External components cannot access internal variables or functions unless you explicitly expose them using defineExpose.

<!-- ChildComponent.vue -->
<script setup>
import { ref } from 'vue'

const formState = ref({ name: '', email: '' })

// The internal action
const resetForm = () => {
  formState.value = { name: '', email: '' }
  console.log('Form reset executed!')
}

// Explicitly grant access to external parents
defineExpose({
  resetForm
})
</script>

<template>
  <form>
    <input v-model="formState.name" placeholder="Name" />
    <input v-model="formState.email" placeholder="Email" />
  </form>
</template>

Step 2: Call the Exposed Method in the Parent (Vue 3.5)

In Vue 3.5+, use useTemplateRef() to obtain a strongly-typed reference to the child component instance, then call the method directly.

<!-- ParentComponent.vue -->
<script setup>
import { useTemplateRef } from 'vue'
import ChildComponent from './ChildComponent.vue'

// Obtain the reference using Vue 3.5's useTemplateRef
const childRef = useTemplateRef('childRef')

const handleResetButtonClick = () => {
  // Directly invoke the exposed method on the child instance
  childRef.value?.resetForm()
}
</script>

<template>
  <div>
    <ChildComponent ref="childRef"/>
    <button @click="handleResetButtonClick">Reset Child Form</button>
  </div>
</template>

The Architectural Balance: When to Use What

A common rule in Vue is "Props Down, Events Up". Reaching into child components with refs should not replace standard data flow, but knowing when to use each pattern keeps your architecture clean:

Scenario	Recommended Pattern	Why
Passing data into a child	Props (`:data="..."`)	Declarative state rendering
Notifying a parent about child actions	Emits (`@submit="..."`)	Decoupled event notification
Triggering imperative child UI actions	`defineExpose` + `useTemplateRef`	Direct command execution without state hacks

Summary

If your component requires a prop and a watch solely to trigger an internal function, you are using reactivity as a workaround for command execution.

Leverage defineExpose alongside Vue 3.5's useTemplateRef() to keep component logic clean, imperative, and free of artificial state flags.

DEV Community: Izak T

Perry Mason in: The Case of the Drifting Timer

Perry Mason in: The Case of the Drifting Timer

Opening Statement

Exhibit A: The Memory Leak

Exhibit B: The Cleanup That Failed

Exhibit C: Scope-Safe Cleanup

Exhibit D: Clock Alignment + Visibility Pause

Clock Alignment

Visibility Pause

SSR Safety

Temporal Precision

The Verdict: The Final Composable

Closing Arguments: Why Recursive setTimeout Instead of setInterval?

Expert Testimony: Why Temporal API Instead of Date?

Case Summary

0041. But it's not magic: if there's no active scope, the callback is never

The Case of the Lying Clock: 5 Vue Mysteries Solved

Case #1: The Lying Clock

Why Does This Happen?

Does This Happen on New Devices Too?

Is This Common Knowledge?

Case #1 Continued: How Recursive setTimeout Fixes the Drift

Case #2: The Box That Didn't Need Tracking — shallowRef vs ref

Case #3: The Cleanup That Worked Everywhere — Effect Scopes and onScopeDispose

The Problem

The Solution

How It Works

Will onMounted and onUnmounted Go Away?

What Happens If You Use Both Inside a Component?

The Catch: No Active Scope

Case #4: The Server That Knew Too Much — Hydration

The Short Version

Why It Matters for Clocks

The Fix

Does This Apply to Every Project?

Case #5: The Warning Nobody Needed — failSilently

Case Closed

Stop Using Props + Watchers Just to Trigger Actions in Child Components (Vue 3.5 useTemplateRef + defineExpose)

Why "Props + Watchers" as Action Triggers is a Smell

The Better Pattern: defineExpose + useTemplateRef

Step 1: Explicitly Expose the Method in the Child

Step 2: Call the Exposed Method in the Parent (Vue 3.5)

The Architectural Balance: When to Use What

Summary

Closing Arguments: Why Recursive `setTimeout` Instead of `setInterval`?

Expert Testimony: Why Temporal API Instead of `Date`?

Case #1 Continued: How Recursive `setTimeout` Fixes the Drift

Case #2: The Box That Didn't Need Tracking — `shallowRef` vs `ref`

Case #3: The Cleanup That Worked Everywhere — Effect Scopes and `onScopeDispose`

Will `onMounted` and `onUnmounted` Go Away?

Case #5: The Warning Nobody Needed — `failSilently`

The Better Pattern: `defineExpose` + `useTemplateRef`