Skip to content
master
Switch branches/tags
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
src
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

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",
        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: () => {},
}

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

🤔 📓