README

⏳ 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",
        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).
`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",
    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: () => {},
    resume: () => {},
    reset: () => {},
}