raddix

useCountDown

@raddix/useCountDown is a custom hook that does the work of handling a countdown timer for you.

You can render its current value into the DOM as it refreshes, and manipulate its behavior as you wish (like specifying an onFinished callback).

Installation

Install the custom hook from the command line.

npm i @raddix/use-count-down

Usage

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 (
<section>
<h1>Pomodoro Timer</h1>
<div>
<sub>Time left</sub>
<p>{count}</p>
</div>
{count > 0 ? (
<div>
<button onClick={() => actions.start()}>Start</button>
<button onClick={actions.stop}>Pause</button>
</div>
) : (
<div>
<p>Time is over!</p>
<button onClick={actions.reset}>Reset timer</button>
</div>
)}
</section>
);
}

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 (
<div>
<p>Are you sure you want to exit?</p>
<div>
<button onClick={exitPage}>Yes, exit</button>
<button onClick={closeModal}>No, stay here</button>
</div>
<sub>Exiting in {count}...</sub>
</div>
);
}

API

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.

IndexDescriptionType
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

NameDescriptionType
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

Parameters

The useCountDown hook takes two setup values.

NameDescriptionRequiredType
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