Skip to content

bradgarropy/use-countdown

Repository files navigation

⏳ useCountdown hook

version downloads size github actions codecov typescript contributing contributors discord

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

next link

📦 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
Brad Garropy

💻 📖 ⚠️ 🚇
Matthew Scholta
Matthew Scholta

💻 📖
James Q Quick
James Q Quick

🤔 📓
Steven Hofheins
Steven Hofheins

📝
Jack Reiker
Jack Reiker

🤔 📓
Mehdi Makhloufi
Mehdi Makhloufi

🤔 📓
Daniel Badir
Daniel Badir

🐛 🤔 📓
Florin Cosmin
Florin Cosmin

💻
Nick DiMatteo
Nick DiMatteo

🐛
Jimmy Longley
Jimmy Longley

🤔
Nuno Fonseca
Nuno Fonseca

🤔
Nathan Arthur
Nathan Arthur

🐛
msopacua
msopacua

🐛 💻