useCountdown
Count down to a deadline. The hook returns the remaining time in milliseconds and leaves the formatting to you.
API
function useCountdown(options?: {
deadline?: number;
duration?: number;
interval?: number;
autoStart?: boolean;
onEnd?: () => void;
}): [
remainingTime: number,
actions: {
start: (options?: { deadline?: number; duration?: number }) => void;
pause: () => void;
resume: () => void;
},
];
Parameters:
deadline: The absolute deadline as a timestamp (epoch milliseconds); takes precedence overduration.duration: The duration in milliseconds, converted to a deadline when the countdown starts.interval: The interval in milliseconds between two state updates, defaults to1000.autoStart: Whether to start counting down on mount, defaults totrue.onEnd: Called once when the deadline of a countdown target is reached.
Results:
remainingTime: The remaining time in milliseconds, never negative.actions: Actions object with a stable identity.actions.start: Start or restart the countdown, counting down to the givendeadlineorduration, falling back to the hook options. It clears any previous countdown first.actions.pause: FreezeremainingTimeuntilresumeis called. Pausing a finished countdown does nothing.actions.resume: Continue counting down from the frozenremainingTime. Does nothing unless paused.
Notes
-
The countdown is driven by the deadline rather than by decrementing a counter, so a throttled background tab never falls behind; it re-synchronizes as soon as the page becomes visible or focused again.
-
Changing the options alone does not restart the countdown.
-
onEndfires once per countdown target, identified by the resolved deadline, so restarting with the samedeadlinedoes not fire it again while restarting withdurationdoes; a target that has already passed fires it once as the countdown starts. -
remainingTimeis seeded fromduration, or from0when onlydeadlineis given, and ends at0; withdeadlinealone the server-rendered value is0, so render the number after mount. -
Each instance runs one timer and tracks one target: rows that share the same deadline can share a single instance, while rows with independent deadlines each need their own.
-
Whether the countdown is paused is not part of the returned value, so record it yourself when the UI needs it.
remainingTimeon its own reads like this:remainingTimeMeaning duration, unchangedNot started yet ( autoStart: false, nostart()call)> 0, decreasing per tickRunning > 0, frozenPaused 0Finished, or never started when only deadlineis given
Example
The example is a one-time-password resend timer: autoStart: false keeps it idle until the code is sent, and onEnd restores the button when the countdown reaches zero.
import { useState } from "react";
import { useCountdown } from "@lilib/hooks";
function Example() {
const [sent, setSent] = useState(false);
const [remainingTime, { start }] = useCountdown({
duration: 60 * 1000,
autoStart: false,
onEnd: () => setSent(false),
});
const send = () => {
setSent(true);
start();
};
return (
<button onClick={send} disabled={sent}>
{sent ? `Resend in ${Math.ceil(remainingTime / 1000)}s` : "Send code"}
</button>
);
}
export default Example;