Nuxt Countdown

A countdown module for multi purpose usage written for Nuxt 3 and 4.

Features

• Nuxt 3 and 4 Support
• Autoimport
• Less config

Documentation

While we're preparing detailed documentation and playground, you can check the examples below.

Quick Setup

1. Add nuxt-countdown dependency to your project

# Using yarn
yarn add nuxt-countdown

# Using npm
npm install nuxt-countdown

# Using pnpm
pnpm add nuxt-countdown

2. Add nuxt-countdown to the modules section of nuxt.config.ts

export default defineNuxtConfig({
  modules: [
    'nuxt-countdown'
  ]
})

That's it! You can now use Countdown Component in your Nuxt app ✨

Examples

When you add this module, the <Countdown> component will be automatically imported into the project.

Basic Usage with Date Object

With :date prop, you can set the target date for countdown.

Then you can use slot props to show the countdown values in days, hours, minutes, seconds or milliseconds. (milliseconds is available for custom interval)

<template>
  <Countdown
      :date="new Date('Oct 19, 2026 16:50:30')"
      v-slot="{ days, hours, minutes, seconds }"
    >
      Time Remaining: {{ days }} days, {{ hours }} hours,
      {{ minutes }} minutes, {{ seconds }} seconds.
  </Countdown>
</template>

Basic Usage with Time in Milliseconds

With :time prop, you can set the target time in milliseconds for countdown.

<template>
  <Countdown
    :time="2 * 24 * 60 * 60 * 1000"
    v-slot="{ days, hours, minutes, seconds }"
  >
    Time Remaining：{{ days }} days, {{ hours }} hours, {{ minutes }} minutes, {{ seconds }} seconds.
  </Countdown>
</template>

Custom Interval

You can set custom interval time value for update countdown values with :interval prop, value in milliseconds.

<template>
  <Countdown
    :time="time"
    :interval="100"
    v-slot="{ days, hours, minutes, seconds, milliseconds }"
  >
    New Year Countdown：{{ days }} days, {{ hours }} hours,
    {{ minutes }} minutes, {{ seconds }}.{{ Math.floor(milliseconds / 100) }}
    seconds.
  </Countdown>
</template>

<script setup lang="ts">
const now: Date = new Date();
const newYear: Date = new Date(now.getFullYear() + 1, 0, 1);
const time: Ref<number> = ref(newYear.getTime() - now.getTime());
<script />

With Years Prop

If you want to show years in countdown, you can use with-years prop. Default value of with-years prop is false. You can set it to true to show years.

<template>
<Countdown
    with-years
    :date="new Date('Oct 19, 2026 16:50:30')"
    v-slot="{ years, days, hours, minutes, seconds }"
  >
    Time Remaining: {{ years }} years, {{ days }} days, {{ hours }} hours,
    {{ minutes }} minutes, {{ seconds }} seconds.
  </Countdown>
</template>

Transform Slot Props

You can modify the slot props provided from component for different purposes with :transform prop.

For example, following code adding 0 in front of the slot values if they are one digit:

<template>
 <Countdown
    :time="2 * 24 * 60 * 60 * 1000"
    :transform="transformSlotProps"
    v-slot="{ days, hours, minutes, seconds }"
  >
    Time Remaining：{{ days }} days, {{ hours }} hours, {{ minutes }} minutes,
    {{ seconds }} seconds.
  </Countdown>
</template>

<script setup lang="ts">
const transformSlotProps = (props: Record<string, number>) => {
  const formattedProps: Record<string, string> = {};

  Object.entries(props).forEach(([key, value]) => {
    formattedProps[key] = (value as number) < 10 ? `0${value}` : String(value);
  });

  return formattedProps;
};
<script />

Tag Prop

You can specify the wrapper element to render with :tag prop. Default value is div.

<template>
 <Countdown
    tag="span"
    :time="2 * 24 * 60 * 60 * 1000"
    v-slot="{ days, hours, minutes, seconds }"
  >
    Time Remaining：{{ days }} days, {{ hours }} hours, {{ minutes }} minutes,
    {{ seconds }} seconds.
  </Countdown>
</template>

Will render as:

<span>
  Time Remaining: 1 days, 23 hours, 59 minutes, 53 seconds. 
</span>

Countdown On Demand

You might want to start countdown after some functionality.

For example, the following code shows how to make disable a button after first click and adding a 60 second countdown until re-enable button.

<template>
  <button type="button" :disabled="counting" @click="startCountdown">
    <Countdown
      v-if="counting"
      v-slot="{ totalSeconds }"
      :time="60100" 
      @end="onCountdownEnd"
    >
      Fetch again {{ totalSeconds }} seconds later
    </Countdown>
    <span v-else>Fetch Verification Code</span>
  </button>
</template>

<script setup lang="ts">
const counting: Ref<boolean> = ref(false);

const startCountdown = () => {
  counting.value = true;
};

const onCountdownEnd = () => {
  counting.value = false;
};
<script />

Total Time Remaining

You can access all total time remaining values with totalDays, totalHours, totalMinutes, totalSeconds slot props.

<template>
  <Countdown
    :date="new Date('Oct 19, 2026 16:50:30')"
    v-slot="{ totalDays, totalHours, totalMinutes, totalSeconds }"
  >
    <br />

    Time Remaining: {{ totalDays }} days or {{ totalHours }} hours or
    {{ totalMinutes }} minutes or {{ totalSeconds }} seconds.
  </Countdown>
</template>

Module Options

With module options, you can set prefix countdown component. You must add countdown key to nuxt.config.ts, here's the example:

export default defineNuxtConfig({
  modules: [
    'nuxt-countdown'
  ],

  countdown: {
    prefix: 'MY' // if it's not defined, you can use the components as shown as in the docs. 
  }
})

With prefix option, then you can use the components as:

<template>
  <MYCountdown />
</template>

Development

# Install dependencies
npm install

# Generate type stubs
npm run dev:prepare

# Develop with the playground
npm run dev

# Build the playground
npm run dev:build

# Run ESLint
npm run lint

# Release new version
npm run release

---

This software is licensed under the MIT License | @volkanakkus | Special thanks to @fengyuanchen 💚