React hook countdown timer. As seen on my Twitch streams.
This package is hosted on npm.
npm install @bradgarropy/use-countdownIn any React component, import useCountdown, then call it like any other hook. The returned countdown value will update every second with the remaining time.
import useCountdown from "@bradgarropy/use-countdown"
const App = () => {
const countdown = useCountdown({
minutes: 1,
seconds: 30,
format: "mm:ss",
autoStart: true,
onCompleted: () => console.log("onCompleted"),
})
console.log(countdown)
// {minutes: 1, seconds: 30, formatted: "01:30", ...}
// {minutes: 1, seconds: 29, formatted: "01:29", ...}
// {minutes: 1, seconds: 28, formatted: "01:28", ...}
// ...
// {minutes: 0, seconds: 0, formatted: "00:00", ...}
// onCompleted()
}| Name | Required | Default | Example | Description |
|---|---|---|---|---|
minutes |
false |
0 |
1 |
Countdown minutes. |
seconds |
false |
0 |
30 |
Countdown seconds. |
format |
false |
mm:ss |
mm:ss:SS |
Format string (reference). |
autoStart |
false |
false |
true |
Whether or not to automatically start the countdown. |
onCompleted |
false |
undefined |
function |
Function to call when countdown completes. |
Starts a countdown timer based on the number of minutes and seconds provided. The returned countdown object updates once per second and stops when the timer hits zero.
The format parameter is a date-fns format string.
If provided, the onCompleted function will be called when the countdown completes.
Here are some examples of how to call useCountdown.
const countdown = useCountdown({
minutes: 1,
seconds: 30,
format: "mm:ss:SS",
autoStart: true,
onCompleted: () => console.log("onCompleted"),
})
const countdown = useCountdown({
minutes: 5,
onCompleted: () => console.log("onCompleted"),
})
const countdown = useCountdown({seconds: 10, format: "mm:ss:SS"})The return object is updated every second until the countdown timer ends.
| Name | Type | Example | Description |
|---|---|---|---|
minutes |
number |
1 |
Remaining minutes. |
seconds |
number |
30 |
Remaining seconds. |
formatted |
string |
01:30 |
Formatted remaining time. |
isActive |
boolean |
true |
Indicates that the countdown is active, either running or paused. |
isInactive |
boolean |
false |
Indicates that the countdown is inactive, and has finished counting down. |
isRunning |
boolean |
true |
Indicates that the countdown is running. |
isPaused |
boolean |
false |
Indicates that the countdown is paused. |
pause |
function |
function |
Pauses the countdown. |
resume |
function |
function |
Resumes the countdown. |
reset |
function |
function |
Resets the countdown. |
Here is an example of the returned object.
{
minutes: 1,
seconds: 30,
formatted: "01:30",
isActive: true,
isInactive: false,
isRunning: true,
isPaused: false,
pause: () => void,
resume: () => void,
reset: (time?: Time) => void,
}🐛 report bugs by filing issues
📢 provide feedback with issues or on twitter
🙋🏼♂️ use my ama or twitter to ask any other questions