Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/dlcastillop/final-countdown-js
A library of React hooks to manage counters, timers and stopwatches.
https://github.com/dlcastillop/final-countdown-js
counter counters stopwatch stopwatches timer timers
Last synced: 6 days ago
JSON representation
A library of React hooks to manage counters, timers and stopwatches.
- Host: GitHub
- URL: https://github.com/dlcastillop/final-countdown-js
- Owner: dlcastillop
- License: mit
- Created: 2023-07-16T17:52:10.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-04-15T22:22:40.000Z (7 months ago)
- Last Synced: 2024-04-15T23:53:46.666Z (7 months ago)
- Topics: counter, counters, stopwatch, stopwatches, timer, timers
- Language: TypeScript
- Homepage: https://github.com/dlcastillop/final-countdown-js#readme
- Size: 481 KB
- Stars: 34
- Watchers: 2
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# 
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.](https://devhunt.org/tool/final-countdown-js)
## Installation
You can use npm, yarn or pnpm to install Final Countdown JS.
```bash
npm install final-countdown-js
```
```bash
yarn add final-countdown-js
```
```bash
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](https://novajs.co/).
### 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:
```tsx
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 (
Counter value: {current.withLeadingZero}
Counter value: {current.withoutLeadingZero}
Is the counter paused? {isPaused ? "Yes" : "No"}
Has the counter over? {isOver ? "Yes" : "No"}
Pause
Play
Reset
Toggle Pause
);
};
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:
```tsx
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 (
Counter value: {current.withLeadingZero}
Counter value: {current.withoutLeadingZero}
Is the counter paused? {isPaused ? "Yes" : "No"}
Has the counter over? {isOver ? "Yes" : "No"}
Pause
Play
Reset
Toggle Pause
);
};
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:
```tsx
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 (
Stopwatch value: {current.withLeadingZero}
Stopwatch value: {current.withoutLeadingZero}
Remaining time: {remainingTime.withLeadingZero}
Remaining time: {remainingTime.withoutLeadingZero}
Days: {currentDays}
Hours: {currentHours}
Minutes: {currentMinutes}
Seconds: {currentSeconds}
Elapsed seconds: {elapsedSeconds}
Remaining seconds: {remainingSeconds}
Is the counter paused? {isPaused ? "Yes" : "No"}
Has the counter over? {isOver ? "Yes" : "No"}
Pause
Play
Reset
Toggle Pause
);
};
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:
```tsx
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 (
Timer value: {current.withLeadingZero}
Timer value: {current.withoutLeadingZero}
Elapsed time: {elapsedTime.withLeadingZero}
Elapsed time: {elapsedTime.withoutLeadingZero}
Days: {currentDays}
Hours: {currentHours}
Minutes: {currentMinutes}
Seconds: {currentSeconds}
Elapsed seconds: {elapsedSeconds}
Remaining seconds: {remainingSeconds}
Is the counter paused? {isPaused ? "Yes" : "No"}
Has the counter over? {isOver ? "Yes" : "No"}
Pause
Play
Reset
Toggle Pause
);
};
export default ReactCounter;
```
## Contributions
If you're interested in contributing to Final Countdown JS, please read our [contributing docs](https://github.com/dlcastillop/final-countdown-js/blob/main/CONTRIBUTING.md) before submitting a pull request.
## Support
Don't forget to leave a star and [a review on Product Hunt!](https://www.producthunt.com/products/final-countdown-js/reviews/new)