Skip to main content

Function: useCooldown()

useCooldown(seconds, options?): UseCooldownReturn

Defined in: use-cooldown.ts:73

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.

Parameters​

seconds​

number

The default cooldown length in seconds.

options?​

UseCooldownOptions

Optional behavior flags.

Returns​

UseCooldownReturn

The countdown state and controls.

Examples​

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