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;
| Parameter | Type | Description |
|---|---|---|
seconds | number | Default cooldown length in seconds. |
options.autoStart | boolean | Begin counting down on mount. Defaults to false. |
options.onComplete | () => void | Called when the countdown reaches 0 by itself. |
Returns: an object with:
| Property | Type | Description |
|---|---|---|
remaining | number | Whole seconds left. 0 when idle. |
isActive | boolean | true while counting down. |
start | (seconds?: number) => void | Start or restart the countdown. Optional one-off duration. |
reset | () => void | Cancel the countdown and set remaining to 0. |
Usage notes
- The hook is idle until you call
start, unlessautoStartis set. - Calling
startwhile 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.secondsis rounded up;0, negative or non-finite values mean no cooldown.- Changing the
secondsargument does not affect a running countdown; the nextstartuses the new value. onCompleteruns only when the countdown finishes on its own, not onreset, restart or unmount. The latest callback is always used.startandresetare 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
useIntervaldirectly.
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
useCooldown sourceuse-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 };
};