Nullifying Precipitation Machine
    Have ideas to improve npm?Join in the discussion! »

    @bradgarropy/use-countdown
    TypeScript icon, indicating that this package has built-in type declarations

    1.2.2 • Public • Published

    useCountdown hook

    version downloads size github actions codecov typescript contributing contributors discord

    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 Example Description
    minutes 1 Remaining minutes.
    seconds 30 Remaining seconds.
    formatted 01:30 Formatted remaining time.

    Here is an example of the returned object.

    {
      minutes: 1,
      seconds: 30,
      formatted: "01:30",
    }

    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

    📝

    Install

    npm i @bradgarropy/use-countdown

    DownloadsWeekly Downloads

    130

    Version

    1.2.2

    License

    MIT

    Unpacked Size

    16.7 kB

    Total Files

    15

    Last publish

    Collaborators

    • avatar