useNumberCountdown

Counts down a duration given in milliseconds. Unlike useDateCountdown, the remaining time is held while paused: resuming continues from where it stopped. Internally the remaining time is recomputed from timestamps on every tick, so it does not accumulate interval drift while running.

Demo

source

0

Years

0

Months

0

Days

0

Hours

0

Minutes

0

Seconds

0

Milliseconds

Usage

<script setup>
import { useNumberCountdown } from "vue-countdown-composable";

const { minutes, seconds, isRunning, start, pause, resume, stop } =
  useNumberCountdown({
    onFinish: () => console.log("Time is up! ⏰"),
  });

// count down 5 minutes, updating every second
start(5 * 60 * 1000);
</script>

<template>
  <div>{{ minutes }}m {{ seconds }}s</div>
</template>

API

Options

useNumberCountdown(options?) accepts an optional options object:

Name	Type	Description
onFinish	() => void	Called once when a started countdown reaches zero. Not called on stop() or when start receives an invalid duration.

Returned values

All values are read-only and reactive.

Name	Type	Description
milliseconds	ComputedRef<number>	Remaining milliseconds (0–999)
seconds	ComputedRef<number>	Remaining seconds (0–59)
minutes	ComputedRef<number>	Remaining minutes (0–59)
hours	ComputedRef<number>	Remaining hours (0–23)
days	ComputedRef<number>	Remaining days (0–29)
months	ComputedRef<number>	Remaining months (0–11), approximated as 30 days
years	ComputedRef<number>	Remaining years, approximated as 12 × 30-day months
isRunning	Readonly<Ref<boolean>>	Whether the countdown is currently ticking

Months and years are approximations

A duration has no calendar context, so months are treated as 30 days and years as 12 of those months.

Methods

Name	Signature	Description
start	(countdownTime: number, updateInterval?: number) => void	Start counting down from countdownTime ms, updating every updateInterval ms (default 1000; invalid values warn and fall back). Calling it again restarts. A non-positive or invalid duration results in a finished (all zeros) countdown.
pause	() => void	Pause the countdown, holding the remaining time.
resume	() => void	Resume a paused countdown from the held remaining time. No-op if already running or finished.
stop	() => void	Stop the countdown and reset all values to zero.

Cleanup

The interval is cleared automatically when the owning component (or effectScope) is disposed — no manual cleanup needed.