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

    1.4.1 • Public • Published

    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

    🤔 📓

    Install

    npm i @bradgarropy/use-countdown

    DownloadsWeekly Downloads

    620

    Version

    1.4.1

    License

    MIT

    Unpacked Size

    22.4 kB

    Total Files

    15

    Last publish

    Collaborators

    • bradgarropy