Nuxt Countdown

A countdown module for multi purpose usage written for Nuxt 3 or newer.

Features

• Nuxt 3 Ready
• 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 ✨

Nuxt 3 Examples

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

Basic Usage with Date Object

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

Basic Usage with Time in Milliseconds

<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.

<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 />

withYears Prop

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

<template>
<Countdown
    v-slot="{ years, days, hours, minutes, seconds }"
    :date="new Date('Oct 19, 2026 16:50:30')"
  >
    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

<template>
  <Countdown
    v-slot="{ totalDays, totalHours, totalMinutes, totalSeconds }"
    :date="new Date('Oct 19, 2026 16:50:30')"
  >
    <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 💚