⏳ 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