Registry / web-framework / vue-timer-hook

vue-timer-hook

library1.0.86jsnpmunverified

Vue Timer Hook is a Vue 3 composition API library providing reactive hooks for common time-based functionalities within components. It offers `useTimer` for countdowns, `useStopwatch` for tracking elapsed time, and `useTime` for continuously retrieving the current time. Currently at version 1.0.86, the library demonstrates a positive version release cadence, with the last publish occurring 3 months ago, indicating active maintenance. Its primary benefit lies in simplifying time-related state management in Vue components, abstracting away complex `setInterval` and `clearInterval` logic, and providing a clean, reactive interface. It is purpose-built for the Vue 3 ecosystem and the Composition API, making it a direct fit for modern Vue projects.

web-framework

npm install vue-timer-hook

package ↗

INSTALL

IMPORT

SIG · VUE-TIMER-HOOK

vue-timer-hook

web-frameworkjavascriptv1.0.86

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

useTimer

✓ import { useTimer } from 'vue-timer-hook'

✗ const useTimer = require('vue-timer-hook')

This library is ESM-only and specifically designed for Vue 3's Composition API. CommonJS `require` syntax will not work.

useStopwatch

✓ import { useStopwatch } from 'vue-timer-hook'

✗ import useStopwatch from 'vue-timer-hook'

`useStopwatch` is a named export, not a default export. Ensure you use curly braces for destructuring.

useTime

✓ import { useTime } from 'vue-timer-hook'

✗ import { useTime } from './vue-timer-hook'

Import directly from the package name `vue-timer-hook`, not a relative path.

This quickstart demonstrates how to create a 10-minute countdown timer using `useTimer`, control it with start, pause, resume, and restart functions, and react to its expiration. It also highlights accessing reactive properties with `.value`.

<template> <div> <h1>Vue Timer Hook Demo</h1> <p>Countdown Timer:</p> <div> <span>{{ timer.days }}</span>:<span>{{ timer.hours }}</span>:<span>{{ timer.minutes }}</span>:<span>{{ timer.seconds }}</span> </div> <p>{{ timer.isRunning.value ? 'Running' : 'Not running' }}</p> <button @click="timer.start()">Start</button> <button @click="timer.pause()">Pause</button> <button @click="timer.resume()">Resume</button> <button @click="restartFive()">Restart to 5 minutes</button> </div> </template> <script setup lang="ts"> import { watchEffect, onMounted, ref } from 'vue' import { useTimer } from 'vue-timer-hook' // Set an initial 10-minute timer const initialTime = new Date() initialTime.setSeconds(initialTime.getSeconds() + 600) // 10 minutes const timer = useTimer(initialTime, { autoStart: true }) const restartFive = () => { // Restarts to a new 5-minute timer const newTime = new Date() newTime.setSeconds(newTime.getSeconds() + 300) timer.restart(newTime) } onMounted(() => { // Watch for the timer to expire watchEffect(() => { if (timer.isExpired.value) { console.log('Timer has expired!') // You could trigger an action here, e.g., show a message } }) }) </script>

Debug

Known issues

breaking`vue-timer-hook` is exclusively designed for Vue 3's Composition API. It is not compatible with Vue 2 or the Options API without significant adaptation, and attempting to use it will lead to runtime errors due to missing Vue 3 specific APIs.

fix

Ensure your project is using Vue 3 and that components are structured with the Composition API (e.g., `<script setup>`).

affects: >=1.0.0

gotchaWhen accessing reactive state properties like `timer.isExpired`, `stopwatch.isRunning`, or any time value (e.g., `timer.seconds`), remember they are Vue `ref` objects and require `.value` to access their current primitive state (e.g., `timer.isExpired.value`, `timer.seconds.value`). Direct access without `.value` will return the ref object itself, potentially leading to incorrect logic or rendering issues.

fix

Always append `.value` when reading or writing to reactive properties returned by the hooks, for example: `if (timer.isExpired.value) { /* ... */ }`.

affects: >=1.0.0

gotchaThe `expiryTimestamp` parameter for `useTimer` expects a JavaScript `Date` object or a numeric timestamp (milliseconds since epoch). Providing other types (e.g., a plain number for seconds) or an invalid `Date` object will result in the timer behaving unexpectedly or not starting at all.

fix

Always initialize `useTimer` with a valid `new Date()` object, ensuring its seconds/minutes are correctly set, or a valid numeric timestamp. For example: `new Date(Date.now() + 60000)` for one minute.

affects: >=1.0.0

gotchaThe `restart` method for `useTimer` requires a *new* `Date` object to define the new expiry timestamp. Reusing and mutating the *same* `Date` object reference passed initially might not trigger reactivity as expected; always create a fresh `Date` for subsequent `restart` calls.

fix

When calling `timer.restart()`, pass a newly created `Date` object, e.g., `timer.restart(new Date(Date.now() + 5 * 60 * 1000))`. For `useStopwatch.restart()`, simply call `stopwatch.restart()` without arguments to reset it.

affects: >=1.0.0

gotchaWhen conditionally rendering components that use `vue-timer-hook` (e.g., with `v-if`), Vue might reuse component instances without re-running setup logic if a `key` attribute is not provided, leading to timers not initializing or resetting correctly.

fix

Use a unique `:key` prop on components using these hooks when they are part of a `v-for` loop or conditionally rendered with `v-if` to ensure proper component lifecycle and re-initialization. For example: `<MyTimerComponent v-if="showTimer" :key="uniqueId" />`.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'value')

Attempting to access a reactive property (e.g., `isRunning`, `isExpired`, `seconds`) from a `vue-timer-hook` return value without appending `.value`.

fix

Access reactive properties using `.value`, for instance: `timer.isRunning.value` or `timer.seconds.value`.

Syntax Error: [plugin:vite:vue] `useTimer` is not defined

The component where the hook is used is not set up for Vue 3 Composition API (e.g., missing `<script setup>`), or the project is using Vue 2.

fix

Ensure your Vue component uses `<script setup lang='ts'>` and your project is configured for Vue 3.

Uncaught TypeError: time.setSeconds is not a function

The `expiryTimestamp` argument provided to `useTimer` is not a valid JavaScript `Date` object or a numeric timestamp.

fix

Ensure `useTimer` is initialized with a properly constructed `new Date()` object, for example: `const time = new Date(); time.setSeconds(time.getSeconds() + 300);`.

Upgrade

Version history

1.0.86latest on npm

Audit

Dependencies

vuerequiredPeer dependency required for Vue 3 Composition API functionality.

Agent activity

7 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://www.npmjs.com/package/vue-timer-hook ↗