Manage a countdown with options to start, stop and reset.


  • Execute a function when the timer has expired.
  • Start the countdown immediately or manually.


Install the custom hook from the command line.

npm i @raddix/use-count-down


Basic example

This example showcases how you could setup a timer for your application.

import { useCountDown } from '@raddix/use-count-down';
export function Timer() {
const initialTime = 30 * 1000; // thirty seconds expressed in miliseconds
const [count, actions] = useCountDown(initialTime, { autoStart: false });
return (
<h1>Pomodoro Timer</h1>
<sub>Time left</sub>
{count > 0 ? (
<button onClick={() => actions.start()}>Start</button>
<button onClick={actions.stop}>Pause</button>
) : (
<p>Time is over!</p>
<button onClick={actions.reset}>Reset timer</button>

Callbacks based on the countdown state

You could setup two callbacks to get called on certain countdown states.

  • onFinished: Gets called when the countdown reaches zero.
  • onTick: Gets called on each countdown interval.
import { useCountDown } from '@raddix/use-count-down';
export function Modal() {
const initialTime = 10 * 1000; // ten seconds expressed in miliseconds
const exitPage = () => {
/* ... */
const closeModal = () => {
/* ... */
const [count] = useCountDown(initialTime, { onFinished: exitPage });
return (
<p>Are you sure you want to exit?</p>
<button onClick={exitPage}>Yes, exit</button>
<button onClick={closeModal}>No, stay here</button>
<sub>Exiting in {count}...</sub>


Return Value

Returns an array that can be destructured into two variables: count and actions. These are reference names, so you can name them as you wish.

0 (count))The current value of the countdown timer. It will stop when it reaches 0.number
1 (actions)An object containing timer manipulation methods.Object

Action Functions

startStarts the timer if it's stopped or configured with `autoStart: false`. It can optionally define a new initial time by passing it as prop. This is useful if you need to add another one second to the timer.function
stopStops the timer.function
resetResets the timer count value. If the timer was configured with `autoStart: true`, it will restart immediately.function


The useCountDown hook takes two setup values.

initialTimeCountdown initial value. It is expressed in miliseconds.Yesnumber
optionsCountdown configuration object.NoObject

Configuration Options

NameDescriptionRequiredDefault ValueType
intervalTime interval for refresing the count value. IMPORTANT: This interval doesn't affect the countdown rate. This is useful if you need to refresh at a slow (~1 second) or fast (~10ms) rate.No1000number
autoStartSpecifies whether the timer should start automatically after being set.Notrueboolean
onFinishedCallback to be executed when the count value reaches 0.Noundefinedfunction
onTickCallback to be executed on each count value refresh.Noundefinedfunction