use-countdown

Count down from a number of ticks to zero.

Minimal setup

Use a Vue 3.5+ project with Vue SFC compilation configured (see Vite+ integration).

vp install @vizejs/composable

Import the entry directly. Call lifecycle-bound utilities inside <script setup> so cleanup follows the component scope; consult the runtime contract for this entry's SSR and hydration behavior.

import { useCountdown } from "@vizejs/composable/use-countdown";

Try it

Wait before resending a sign-in code

Count down a cooldown after an action, keep the button disabled until it ends, and allow another request afterwards.

Open the interactive example

What to observe: Send code starts a 30-second cooldown and disables the button while the remaining seconds count down. When it reaches zero the button reads Resend code again and the message counts the codes sent.

start() resets to the initial count and begins ticking; isActive is true while the timer runs. Call useCountdown inside setup so its interval is cleared with the component. Pass intervalMs for a different tick length.

Compare the initial and interacted states

Copy the example

Save this complete SFC in your Vue project. Its public imports and source are the same ones executed in the preview.

<script setup lang="ts">
import { ref } from "vue";
import { useCountdown } from "@vizejs/composable/use-countdown";

const sent = ref(0);
const { remaining, isActive, start } = useCountdown(30);

function sendCode() {
  sent.value += 1;
  start();
}
</script>

<template>
  <div class="composable-example">
    <p>Let a reader request a new sign-in code, then wait before asking again.</p>
    <button type="button" :disabled="isActive" @click="sendCode">
      {{ sent === 0 ? "Send code" : "Resend code" }}
    </button>
    <output aria-live="polite">{{
      sent === 0
        ? "No code sent yet."
        : isActive
          ? `Code sent. Resend available in ${remaining} s.`
          : `Code sent ${sent} times. You can request another one.`
    }}</output>
  </div>
</template>

Runtime contract

API

useCountdown

Count down from a number of ticks to zero. Builds on useIntervalFn: pause/resume keep the remaining count, start and reset restore it, and the timer pauses itself at zero after calling onComplete. The initial count is reactive only for later start()/reset() calls without an argument. Server rendering is hydration-stable (no timer, remaining stays at the initial count).

function useCountdown( initialCount: MaybeRefOrGetter<number>, options: UseCountdownOptions = {}, ): CountdownControls

const { remaining, start } = useCountdown(60, { onComplete: resendAvailable });
start();

Types

UseCountdownOptions

Options for useCountdown.

CountdownControls

State and controls returned by useCountdown.