⏳ useCountdown hook

React hook countdown timer. As seen on my Twitch streams.

📦 Installation

This package is hosted on npm.

npm install @bradgarropy/use-countdown

🥑 Usage

In 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()
}

📖 API Reference

useCountdown({minutes, seconds})

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,
}

❔ Questions

🐛 report bugs by filing issues
📢 provide feedback with issues or on twitter
🙋🏼‍♂️ use my ama or twitter to ask any other questions

✨ Contributors

Brad Garropy 💻 📖 ⚠️ 🚇	Matthew Scholta 💻 📖	James Q Quick 🤔 📓	Steven Hofheins 📝 ✅	Jack Reiker 🤔 📓	Mehdi Makhloufi 🤔 📓	Daniel Badir 🐛 🤔 📓
Florin Cosmin 💻	Nick DiMatteo 🐛	Jimmy Longley 🤔	Nuno Fonseca 🤔	Nathan Arthur 🐛	msopacua 🐛 💻