README.md

Final Countdown JS

Final Countdown JS is a library of React hooks to manage counters, timers and stopwatches.

Featured

Featured on DevHunt with 19 upvotes ending up in the 6th position of the week.

Installation

You can use npm, yarn or pnpm to install Final Countdown JS.

npm install final-countdown-js

yarn add final-countdown-js

pnpm install final-countdown-js

Hooks

Note

Do you want to use these hooks, but without installing an extra dependency? Try Nova.js: a collection of dependency-free React hooks.

useCountDown

The useCountDown hook provides a simple countdown timer functionality.

It takes three arguments:

• min (number): the initial value of the counter.
• max(number): the final value of the counter. It has to be greater than min.
• options(optional object): the options for the counter.
  • startPaused (optional boolean): determines whether the counter should start in a paused state. Defaults to false.
  • onFinish (optional function): a function that will be called when the counter reaches the final value.

It returns an object with the following props:

• current: an object holding the current time of the counter in both leading zero and non-leading zero formats. This object has two properties:
  • withLeadingZero: a string indicating the current time of the counter with leading zeroes where necessary.
  • withoutLeadingZero: a string indicating the current time of the counter without leading zeros.
• isPaused: a boolean value indicating if the counter is currently paused.
• isOver: a boolean value indicating if the counter has finished running.
• pause: a function that, when called, will pause the counter.
• play: a function that, when called, will resume (or start) the counter.
• reset: a function that, when called, will reset the counter.
• togglePause: a function that, when called, will toggle between pausing and playing the counter.

Example:

import { useCountDown } from "final-countdown-js";

const ReactCounter = () => {
  const { current, isPaused, isOver, pause, play, reset, togglePause } =
    useCountDown(0, 10, {
      startPaused: false,
      onFinish: () => console.log("Counter ended"),
    });

  return (
    <div>
      <p>Counter value: {current.withLeadingZero}</p>
      <p>Counter value: {current.withoutLeadingZero}</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 ReactCounter;

useCountUp

The useCountUp hook provides a simple countup timer functionality.

It takes three arguments:

• min (number): the initial value of the counter.
• max(number): the final value of the counter. It has to be greater than min.
• options(optional object): the options for the counter.
  • startPaused (optional boolean): determines whether the counter should start in a paused state. Defaults to false.
  • onFinish (optional function): a function that will be called when the counter reaches the final value.

It returns an object with the following props:

• current: an object holding the current time of the counter in both leading zero and non-leading zero formats. This object has two properties:
  • withLeadingZero: a string indicating the current time of the counter with leading zeroes where necessary.
  • withoutLeadingZero: a string indicating the current time of the counter without leading zeros.
• isPaused: a boolean value indicating if the counter is currently paused.
• isOver: a boolean value indicating if the counter has finished running.
• pause: a function that, when called, will pause the counter.
• play: a function that, when called, will resume (or start) the counter.
• reset: a function that, when called, will reset the counter.
• togglePause: a function that, when called, will toggle between pausing and playing the counter.

Example:

import { useCountUp } from "final-countdown-js";

const ReactCounter = () => {
  const { current, isPaused, isOver, pause, play, reset, togglePause } =
    useCountUp(0, 10, {
      startPaused: false,
      onFinish: () => console.log("Counter ended"),
    });

  return (
    <div>
      <p>Counter value: {current.withLeadingZero}</p>
      <p>Counter value: {current.withoutLeadingZero}</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 ReactCounter;

useStopwatch

The useStopwatch hook provides stopwatch functionality with or without a limit.

It takes one argument:

• options(optional object): the options for the stopwatch.
  • endTime (options string): specifies the time at which the stopwatch will stop. It must be in dd:hh:mm:ss format. If not specified, the stopwatch will not end.
  • startPaused (optional boolean): determines whether the stopwatch should start in a paused state. Defaults to false.
  • onFinish (optional function): a function that will be called when the stopwatch reaches the final value.
  • separator (optional string): specifies the separator to be used between days, hours, minutes, and seconds when the time is represented as a string. By default, colon (:) is used as a separator.

It returns an object with the following props:

• current: an object holding the current time of the stopwatch in both leading zero and non-leading zero formats. This object has two properties:
  • withLeadingZero: a string indicating the current time of the stopwatch with leading zeroes where necessary.
  • withoutLeadingZero: a string indicating the current time of the stopwatch without leading zeros.
• isPaused: a boolean value indicating if the stopwatch is currently paused.
• isOver: a boolean value indicating if the stopwatch has finished running.
• currentDays: a number indicating the current value of the days on the stopwatch.
• currentHours: a number indicating the current value of the hours on the stopwatch.
• currentMinutes: a number indicating the current value of the minutes on the stopwatch.
• currentSeconds: a number indicating the current value of the seconds on the stopwatch.
• elapsedSeconds: a number indicating the total elapsed time, calculated in seconds, since the stopwatch started.
• remainingSeconds: a number indicating the total remaining time, calculated in seconds, until the stopwatch reaches the initially set time. If endTime is not specified, it will always be 0.
• remainingTime: analogous to the current object, this object holds the remaining time in both formats:
  • withLeadingZero: a string indicating the remaining time with leading zeroes. If endTime is not specified, it will always be 00:00:00:00.
  • withoutLeadingZero: a string indicating the remaining time without leading zeroes. If endTime is not specified, it will always be 0:0:0:0.
• pause: a function that, when called, will pause the stopwatch.
• play: a function that, when called, will resume (or start) the stopwatch.
• reset: a function that, when called, will reset the stopwatch.
• togglePause: a function that, when called, will toggle between pausing and playing the stopwatch.

Example:

import { useStopwatch } from "final-countdown-js";

const ReactCounter = () => {
  const {
    current,
    remainingTime,
    currentDays,
    currentHours,
    currentMinutes,
    currentSeconds,
    elapsedSeconds,
    remainingSeconds,
    isPaused,
    isOver,
    pause,
    play,
    reset,
    togglePause,
  } = useStopwatch({
    endTime: "00:00:00:10",
    startPaused: true,
    separator: "-",
    onFinish: () => console.log("Stopwatch ended"),
  });

  return (
    <div>
      <p>Stopwatch value: {current.withLeadingZero}</p>
      <p>Stopwatch value: {current.withoutLeadingZero}</p>
      <p>Remaining time: {remainingTime.withLeadingZero}</p>
      <p>Remaining time: {remainingTime.withoutLeadingZero}</p>
      <p>Days: {currentDays}</p>
      <p>Hours: {currentHours}</p>
      <p>Minutes: {currentMinutes}</p>
      <p>Seconds: {currentSeconds}</p>
      <p>Elapsed seconds: {elapsedSeconds}</p>
      <p>Remaining seconds: {remainingSeconds}</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 ReactCounter;

useTimer

The useTimer hook provides timer functionality.

It takes two arguments:

• startTime (string): specifies the time at which the timer will start. It must be in dd:hh:mm:ss format.
• options(optional object): the options for the timer.
  • startPaused (optional boolean): determines whether the timer should start in a paused state. Defaults to false.
  • onFinish (optional function): a function that will be called when the timer reaches the final value.
  • separator (optional string): specifies the separator to be used between days, hours, minutes, and seconds when the time is represented as a string. By default, colon (:) is used as a separator.

It returns an object with the following props:

• current: an object holding the current time of the timer in both leading zero and non-leading zero formats. This object has two properties:
  • withLeadingZero: a string indicating the current time of the timer with leading zeroes where necessary.
  • withoutLeadingZero: a string indicating the current time of the timer without leading zeros.
• isPaused: a boolean value indicating if the timer is currently paused.
• isOver: a boolean value indicating if the timer has finished running.
• currentDays: a number indicating the current value of the days on the timer.
• currentHours: a number indicating the current value of the hours on the timer.
• currentMinutes: a number indicating the current value of the minutes on the timer.
• currentSeconds: a number indicating the current value of the seconds on the timer.
• elapsedSeconds: a number indicating the total elapsed time, calculated in seconds, since the timer started.
• remainingSeconds: a number indicating the total remaining time, calculated in seconds, until the timer reaches the initially set time.
• elapsedTime: analogous to the current object, this object holds the elapsed time in both formats:
  • withLeadingZero: a string indicating the elapsed time with leading zeroes.
  • withoutLeadingZero: a string indicating the elapsed time without leading zeroes.
• pause: a function that, when called, will pause the timer.
• play: a function that, when called, will resume (or start) the timer.
• reset: a function that, when called, will reset the timer.
• togglePause: a function that, when called, will toggle between pausing and playing the timer.

Example:

import { useTimer } from "final-countdown-js";

const ReactCounter = () => {
  const {
    current,
    elapsedTime,
    currentDays,
    currentHours,
    currentMinutes,
    currentSeconds,
    elapsedSeconds,
    remainingSeconds,
    isPaused,
    isOver,
    pause,
    play,
    reset,
    togglePause,
  } = useTimer("00:00:00:10", {
    startPaused: true,
    separator: "-",
    onFinish: () => console.log("Timer ended"),
  });

  return (
    <div>
      <p>Timer value: {current.withLeadingZero}</p>
      <p>Timer value: {current.withoutLeadingZero}</p>
      <p>Elapsed time: {elapsedTime.withLeadingZero}</p>
      <p>Elapsed time: {elapsedTime.withoutLeadingZero}</p>
      <p>Days: {currentDays}</p>
      <p>Hours: {currentHours}</p>
      <p>Minutes: {currentMinutes}</p>
      <p>Seconds: {currentSeconds}</p>
      <p>Elapsed seconds: {elapsedSeconds}</p>
      <p>Remaining seconds: {remainingSeconds}</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 ReactCounter;

Contributions

If you're interested in contributing to Final Countdown JS, please read our contributing docs before submitting a pull request.

Support

Don't forget to leave a star and a review on Product Hunt!