Get Started

Vue Countdown Composable is a set of countdown utilities built on the Composition API. We assume you are already familiar with the basic ideas of the Composition API before you continue.

Installation

npm i vue-countdown-composable

Usage Example

Simply import the functions you need from vue-countdown-composable:

• useDateCountdown to count down to a future date
• useNumberCountdown to count down a duration in milliseconds
• useStopwatch to count up from zero

useDateCountdown

For details and demo refer to useDateCountdown

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

// exposes computed properties and methods
const { seconds, minutes, hours, days, start } = useDateCountdown();
const futureDate = new Date("2040-08-13");

// start counting down towards the future date
start(futureDate);
</script>

<template>
  <div>Days: {{ days }}</div>
  <div>Hours: {{ hours }}</div>
  <div>Minutes: {{ minutes }}</div>
  <div>Seconds: {{ seconds }}</div>
</template>

useNumberCountdown

For details and demo refer to useNumberCountdown

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

// exposes computed properties and methods
const { seconds, minutes, hours, days, start } = useNumberCountdown();

// time in milliseconds
const TEN_DAYS_IN_MILLISECONDS = 864_000_000;

// start counting down the duration
start(TEN_DAYS_IN_MILLISECONDS);
</script>

<template>
  <div>Days: {{ days }}</div>
  <div>Hours: {{ hours }}</div>
  <div>Minutes: {{ minutes }}</div>
  <div>Seconds: {{ seconds }}</div>
</template>

useStopwatch

For details and demo refer to useStopwatch

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

// exposes computed properties and methods
const { minutes, seconds, start, pause, resume, stop } = useStopwatch();

// count up from zero, updating every second
start();
</script>

<template>
  <div>Minutes: {{ minutes }}</div>
  <div>Seconds: {{ seconds }}</div>
</template>

Reacting to the end of a countdown

Both countdown composables accept an onFinish callback, called once when a started countdown reaches zero:

const { start } = useNumberCountdown({
  onFinish: () => console.log("Time is up! ⏰"),
});

TypeScript

The package ships full type declarations. Besides the composables, it exports the CountdownObject type (the { milliseconds, seconds, minutes, hours, days, months, years } shape), the UseCountdownOptions type, and the DEFAULT_UPDATE_INTERVAL_MS constant (1000).

Vapor Mode

Both composables are compatible with Vapor mode, introduced in Vue 3.6 (in release candidate at the time of writing). They are built exclusively on Vue's reactivity APIs (ref, computed, onScopeDispose), which behave identically in Vapor and Virtual DOM components — no renderer-specific or internal APIs are used. You can use them in <script setup vapor> components without any changes.

SSR

The countdown only starts when you call start(), and cleanup is handled automatically via onScopeDispose. No timers are created at import time, so the composables are safe to use in SSR environments — call start() in onMounted (or any client-only code path) if you want the countdown to begin on the client.