Skip to main content

useCooldown

A one-second countdown for actions that must not be repeated straight away. It returns the whole seconds left plus controls to start, restart or cancel the countdown.

When to use it​

  • "Resend verification email" or "Request a new code" buttons.
  • Honoring a server's Retry-After / rate-limit response.
  • Any short lock-out after an action, with a visible "try again in Ns".

Demo​

Click Resend email and watch the button count down; open the Console tab to see onComplete fire. In the second demo, each attempt overrides the duration and Skip wait cancels it.

Loading demo…

Signature​

interface UseCooldownOptions {
autoStart?: boolean;
onComplete?: () => void;
}

interface UseCooldownReturn {
remaining: number;
isActive: boolean;
start: (seconds?: number) => void;
reset: () => void;
}

function useCooldown(
seconds: number,
options?: UseCooldownOptions
): UseCooldownReturn;
ParameterTypeDescription
secondsnumberDefault cooldown length in seconds.
options.autoStartbooleanBegin counting down on mount. Defaults to false.
options.onComplete() => voidCalled when the countdown reaches 0 by itself.

Returns: an object with:

PropertyTypeDescription
remainingnumberWhole seconds left. 0 when idle.
isActivebooleantrue while counting down.
start(seconds?: number) => voidStart or restart the countdown. Optional one-off duration.
reset() => voidCancel the countdown and set remaining to 0.

Usage notes​

  • The hook is idle until you call start, unless autoStart is set.
  • Calling start while a countdown is running restarts it from the full duration.
  • start(seconds) overrides the duration for that run only, which suits server-provided wait times. seconds is rounded up; 0, negative or non-finite values mean no cooldown.
  • Changing the seconds argument does not affect a running countdown; the next start uses the new value.
  • onComplete runs only when the countdown finishes on its own, not on reset, restart or unmount. The latest callback is always used.
  • start and reset are stable across renders.
  • The pause between ticks is never shorter than a second, but browsers may delay timers in background tabs. For a hard deadline, compare timestamps.
  • Need a countdown that also pauses? Use useInterval directly.

Example​

const { remaining, isActive, start } = useCooldown(30);

const resend = async () => {
await sendVerificationEmail();
start();
};

<button onClick={resend} disabled={isActive}>
{isActive ? `Resend in ${remaining}s` : "Resend email"}
</button>;

Hook source​

View useCooldown source

use-cooldown.ts
import { useCallback, useEffect, useState } from "react";

import { useLatest } from "./use-latest";

/** Options for {@link useCooldown}. */
export interface UseCooldownOptions {
/** Begin the countdown on mount instead of waiting for `start`. Default is `false`. */
autoStart?: boolean;
/** Called when a countdown reaches `0` on its own. Not called by `reset`. */
onComplete?: () => void;
}

/** Value returned by {@link useCooldown}. */
export interface UseCooldownReturn {
/** Whole seconds left. `0` when idle. */
remaining: number;
/** `true` while a countdown is running (`remaining > 0`). */
isActive: boolean;
/**
* Begin a fresh countdown from `seconds`, restarting it if one is already
* running. Pass a number to override the hook's `seconds` for this run only.
*/
start: (seconds?: number) => void;
/** Stop the countdown and set `remaining` back to `0`, without `onComplete`. */
reset: () => void;
}

// Invalid input (NaN, negative, Infinity) is treated as "no cooldown".
const toSeconds = (value: number): number =>
Number.isFinite(value) ? Math.max(0, Math.ceil(value)) : 0;

/**
* A one-second countdown for actions that must not be repeated straight away,
* such as "Resend email" or "Request a new code" buttons.
*
* The countdown is idle (`remaining` is `0`) until you call `start`, unless
* `autoStart` is set. Calling `start` again restarts it from the full
* duration. `seconds` is rounded up to a whole number; invalid or negative
* values mean no cooldown. Changing `seconds` while a countdown runs does not
* affect it; the new value is used by the next `start`.
*
* Each tick is a timer re-armed every second, so the pause is never shorter
* than a second but browsers may delay it in background tabs. The timer is
* cleared on unmount, and `onComplete` is never called after unmount.
*
* @param seconds - The default cooldown length in seconds.
* @param options - Optional {@link UseCooldownOptions | behavior} flags.
* @returns The {@link UseCooldownReturn | countdown state and controls}.
*
* @example
* ```tsx
* const { remaining, isActive, start } = useCooldown(30);
*
* const resend = async () => {
* await sendVerificationEmail();
* start();
* };
*
* <button onClick={resend} disabled={isActive}>
* {isActive ? `Resend in ${remaining}s` : "Resend email"}
* </button>;
* ```
*
* @example
* ```ts
* // Honor a server-provided wait time and react when it ends
* const { start } = useCooldown(60, { onComplete: () => setCanRetry(true) });
* start(retryAfterSeconds);
* ```
*
* For a live, editable example, see the [useCooldown docs page](https://altalyst-solutions.github.io/hookify/hooks/use-cooldown).
*/
export const useCooldown = (
seconds: number,
options?: UseCooldownOptions
): UseCooldownReturn => {
// A fresh object per start/tick so restarting at the same value re-arms the timer.
const [state, setState] = useState(() => ({
remaining: options?.autoStart ? toSeconds(seconds) : 0,
}));
const secondsRef = useLatest(seconds);
const onCompleteRef = useLatest(options?.onComplete);
const { remaining } = state;

useEffect(() => {
if (remaining <= 0) return;

const id = setTimeout(() => {
setState({ remaining: remaining - 1 });
if (remaining === 1) onCompleteRef.current?.();
}, 1000);
return () => clearTimeout(id);
}, [state, remaining, onCompleteRef]);

const start = useCallback(
(override?: number) =>
setState({ remaining: toSeconds(override ?? secondsRef.current) }),
[secondsRef]
);

const reset = useCallback(() => setState({ remaining: 0 }), []);

return { remaining, isActive: remaining > 0, start, reset };
};