useCountdown

React hook to create a countdown functionality.

Add the hook via the CLI:

npm

npx @novajslabs/cli add useCountdown

yarn

npx @novajslabs/cli add useCountdown

pnpm

pnpm dlx @novajslabs/cli add useCountdown

Or copy and paste the code into your project:

TypeScript

import { useState, useEffect } from "react";

interface Counter {
  current: string;
  isPaused: boolean;
  isOver: boolean;
  pause: () => void;
  play: () => void;
  reset: () => void;
  togglePause: () => void;
}

export const useCountdown = (min: number, max: number): Counter => {
  const [count, setCount] = useState(max);
  const [paused, setPaused] = useState(false);
  const [isOver, setIsOver] = useState(false);

  useEffect(() => {
    if (paused) {
      return;
    }

    const interval = setInterval(() => {
      setCount((prev) => prev - 1);
    }, 1000);

    if (count <= min) {
      setIsOver(true);
      clearInterval(interval);
      return;
    }

    return () => clearInterval(interval);
  }, [count, min, max, paused]);

  return {
    current: count.toString(),
    isPaused: paused,
    isOver,
    pause: () => setPaused(true),
    play: () => setPaused(false),
    reset: () => {
      setIsOver(false);
      setCount(max);
    },
    togglePause: () => {
      setPaused(!paused);
    },
  };
};

JavaScript

import { useState, useEffect } from "react";

export const useCountdown = (min, max) => {
  const [count, setCount] = useState(max);
  const [paused, setPaused] = useState(false);
  const [isOver, setIsOver] = useState(false);

  useEffect(() => {
    if (paused) {
      return;
    }

    const interval = setInterval(() => {
      setCount((prev) => prev - 1);
    }, 1000);

    if (count <= min) {
      setIsOver(true);
      clearInterval(interval);
      return;
    }

    return () => clearInterval(interval);
  }, [count, min, max, paused]);

  return {
    current: count.toString(),
    isPaused: paused,
    isOver,
    pause: () => setPaused(true),
    play: () => setPaused(false),
    reset: () => {
      setIsOver(false);
      setCount(max);
    },
    togglePause: () => {
      setPaused(!paused);
    },
  };
};

Requirements

React 16.8 or higher

Parameters

min required

• Type: number

The final value of the counter.

max required

• Type: number

The initial value of the counter.

Return values

current

• Type: string

The current value of the counter.

isPaused

• Type: boolean

Represents whether the counter is paused (true) or not (false).

isOver

• Type: boolean

Represents whether the counter has ended paused (true) or not (false).

pause

• Type: function

Pause the counter.

play

• Type: function

Play the counter.

reset

• Type: function

Reset the counter.

togglePause

• Type: function

Toggle between pausing and playing the counter.

Example

import { useCountdown } from "./hooks/useCountdown";

const App = () => {
  const { current, isPaused, isOver, pause, play, reset, togglePause } =
    useCountdown(0, 10);

  return (
    <div>
      <p>Counter value: {current}</p>
      <p>Is the counter paused? {isPaused ? "Yes" : "No"}</p>
      <p>Has the counter over? {isOver ? "Yes" : "No"}</p>
      <button onClick={pause}>Pause</button>
      <button onClick={play}>Play</button>
      <button onClick={reset}>Reset</button>
      <button onClick={togglePause}>Toggle Pause</button>
    </div>
  );
};

export default App;

Use cases

Here are some use cases where this React hook is useful:

• Creating a countdown timer for an online quiz application
• Implementing a time-limited task completion feature in a productivity tool
• Developing a countdown clock for an online auction platform
• Adding a time-limited challenge mode to a fitness tracking app
• Integrating a countdown timer for a time-bound multiplayer game lobby