{"id":19080514,"url":"https://github.com/dlcastillop/final-countdown-js","last_synced_at":"2026-03-08T14:31:13.932Z","repository":{"id":183288943,"uuid":"667121199","full_name":"dlcastillop/final-countdown-js","owner":"dlcastillop","description":"A library of React hooks to manage counters, timers and stopwatches.","archived":false,"fork":false,"pushed_at":"2024-04-15T22:22:40.000Z","size":493,"stargazers_count":37,"open_issues_count":2,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-30T06:11:22.263Z","etag":null,"topics":["counter","counters","stopwatch","stopwatches","timer","timers"],"latest_commit_sha":null,"homepage":"https://github.com/dlcastillop/final-countdown-js#readme","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dlcastillop.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"ko_fi":"dlcastillop"}},"created_at":"2023-07-16T17:52:10.000Z","updated_at":"2024-10-11T08:56:52.000Z","dependencies_parsed_at":"2024-01-28T17:38:32.457Z","dependency_job_id":"3e41d44d-b02d-411a-8d34-26d517a78046","html_url":"https://github.com/dlcastillop/final-countdown-js","commit_stats":null,"previous_names":["dlcastillop/final-countdown-js"],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dlcastillop%2Ffinal-countdown-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dlcastillop%2Ffinal-countdown-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dlcastillop%2Ffinal-countdown-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dlcastillop%2Ffinal-countdown-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dlcastillop","download_url":"https://codeload.github.com/dlcastillop/final-countdown-js/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251651231,"owners_count":21621716,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["counter","counters","stopwatch","stopwatches","timer","timers"],"created_at":"2024-11-09T02:24:14.095Z","updated_at":"2026-03-08T14:31:13.878Z","avatar_url":"https://github.com/dlcastillop.png","language":"TypeScript","funding_links":["https://ko-fi.com/dlcastillop"],"categories":[],"sub_categories":[],"readme":"# \u003cimg src=\"https://github.com/dlcastillop/dlcastillop/blob/main/logos/final-countdown-js-logo.png\" width=\"40\" height=\"40\" /\u003e Final Countdown JS\n\nFinal Countdown JS is a library of React hooks to manage counters, timers and stopwatches.\n\n## Featured\n\n\u003ca href=\"https://www.producthunt.com/posts/final-countdown-js?utm_source=badge-featured\u0026utm_medium=badge\u0026utm_souce=badge-final\u0026#0045;countdown\u0026#0045;js\" target=\"_blank\"\u003e\u003cimg src=\"https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=410431\u0026theme=neutral\" alt=\"Final\u0026#0032;Countdown\u0026#0032;JS - A\u0026#0032;react\u0026#0032;hook\u0026#0032;library\u0026#0032;to\u0026#0032;handle\u0026#0032;all\u0026#0032;kinds\u0026#0032;of\u0026#0032;timers | Product Hunt\" style=\"width: 250px; height: 54px;\" width=\"250\" height=\"54\" /\u003e\u003c/a\u003e\n\n[Featured on DevHunt with 19 upvotes ending up in the 6th position of the week.](https://devhunt.org/tool/final-countdown-js)\n\n## Installation\n\nYou can use npm, yarn or pnpm to install Final Countdown JS.\n\n```bash\nnpm install final-countdown-js\n```\n\n```bash\nyarn add final-countdown-js\n```\n\n```bash\npnpm install final-countdown-js\n```\n\n## Hooks\n\n\u003e [!NOTE]  \n\u003e 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/).\n\n### useCountDown\n\nThe useCountDown hook provides a simple countdown timer functionality.\n\nIt takes three arguments:\n\n- `min` (number): the initial value of the counter.\n- `max`(number): the final value of the counter. It has to be greater than `min`.\n- `options`(optional object): the options for the counter.\n  - `startPaused` (optional boolean): determines whether the counter should start in a paused state. Defaults to false.\n  - `onFinish` (optional function): a function that will be called when the counter reaches the final value.\n\nIt returns an object with the following props:\n\n- `current`: an object holding the current time of the counter in both leading zero and non-leading zero formats. This object has two properties:\n  - `withLeadingZero`: a string indicating the current time of the counter with leading zeroes where necessary.\n  - `withoutLeadingZero`: a string indicating the current time of the counter without leading zeros.\n- `isPaused`: a boolean value indicating if the counter is currently paused.\n- `isOver`: a boolean value indicating if the counter has finished running.\n- `pause`: a function that, when called, will pause the counter.\n- `play`: a function that, when called, will resume (or start) the counter.\n- `reset`: a function that, when called, will reset the counter.\n- `togglePause`: a function that, when called, will toggle between pausing and playing the counter.\n\nExample:\n\n```tsx\nimport { useCountDown } from \"final-countdown-js\";\n\nconst ReactCounter = () =\u003e {\n  const { current, isPaused, isOver, pause, play, reset, togglePause } =\n    useCountDown(0, 10, {\n      startPaused: false,\n      onFinish: () =\u003e console.log(\"Counter ended\"),\n    });\n\n  return (\n    \u003cdiv\u003e\n      \u003cp\u003eCounter value: {current.withLeadingZero}\u003c/p\u003e\n      \u003cp\u003eCounter value: {current.withoutLeadingZero}\u003c/p\u003e\n      \u003cp\u003eIs the counter paused? {isPaused ? \"Yes\" : \"No\"}\u003c/p\u003e\n      \u003cp\u003eHas the counter over? {isOver ? \"Yes\" : \"No\"}\u003c/p\u003e\n      \u003cbutton onClick={pause}\u003ePause\u003c/button\u003e\n      \u003cbutton onClick={play}\u003ePlay\u003c/button\u003e\n      \u003cbutton onClick={reset}\u003eReset\u003c/button\u003e\n      \u003cbutton onClick={togglePause}\u003eToggle Pause\u003c/button\u003e\n    \u003c/div\u003e\n  );\n};\n\nexport default ReactCounter;\n```\n\n### useCountUp\n\nThe useCountUp hook provides a simple countup timer functionality.\n\nIt takes three arguments:\n\n- `min` (number): the initial value of the counter.\n- `max`(number): the final value of the counter. It has to be greater than `min`.\n- `options`(optional object): the options for the counter.\n  - `startPaused` (optional boolean): determines whether the counter should start in a paused state. Defaults to false.\n  - `onFinish` (optional function): a function that will be called when the counter reaches the final value.\n\nIt returns an object with the following props:\n\n- `current`: an object holding the current time of the counter in both leading zero and non-leading zero formats. This object has two properties:\n  - `withLeadingZero`: a string indicating the current time of the counter with leading zeroes where necessary.\n  - `withoutLeadingZero`: a string indicating the current time of the counter without leading zeros.\n- `isPaused`: a boolean value indicating if the counter is currently paused.\n- `isOver`: a boolean value indicating if the counter has finished running.\n- `pause`: a function that, when called, will pause the counter.\n- `play`: a function that, when called, will resume (or start) the counter.\n- `reset`: a function that, when called, will reset the counter.\n- `togglePause`: a function that, when called, will toggle between pausing and playing the counter.\n\nExample:\n\n```tsx\nimport { useCountUp } from \"final-countdown-js\";\n\nconst ReactCounter = () =\u003e {\n  const { current, isPaused, isOver, pause, play, reset, togglePause } =\n    useCountUp(0, 10, {\n      startPaused: false,\n      onFinish: () =\u003e console.log(\"Counter ended\"),\n    });\n\n  return (\n    \u003cdiv\u003e\n      \u003cp\u003eCounter value: {current.withLeadingZero}\u003c/p\u003e\n      \u003cp\u003eCounter value: {current.withoutLeadingZero}\u003c/p\u003e\n      \u003cp\u003eIs the counter paused? {isPaused ? \"Yes\" : \"No\"}\u003c/p\u003e\n      \u003cp\u003eHas the counter over? {isOver ? \"Yes\" : \"No\"}\u003c/p\u003e\n      \u003cbutton onClick={pause}\u003ePause\u003c/button\u003e\n      \u003cbutton onClick={play}\u003ePlay\u003c/button\u003e\n      \u003cbutton onClick={reset}\u003eReset\u003c/button\u003e\n      \u003cbutton onClick={togglePause}\u003eToggle Pause\u003c/button\u003e\n    \u003c/div\u003e\n  );\n};\n\nexport default ReactCounter;\n```\n\n### useStopwatch\n\nThe useStopwatch hook provides stopwatch functionality with or without a limit.\n\nIt takes one argument:\n\n- `options`(optional object): the options for the stopwatch.\n  - `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.\n  - `startPaused` (optional boolean): determines whether the stopwatch should start in a paused state. Defaults to false.\n  - `onFinish` (optional function): a function that will be called when the stopwatch reaches the final value.\n  - `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.\n\nIt returns an object with the following props:\n\n- `current`: an object holding the current time of the stopwatch in both leading zero and non-leading zero formats. This object has two properties:\n  - `withLeadingZero`: a string indicating the current time of the stopwatch with leading zeroes where necessary.\n  - `withoutLeadingZero`: a string indicating the current time of the stopwatch without leading zeros.\n- `isPaused`: a boolean value indicating if the stopwatch is currently paused.\n- `isOver`: a boolean value indicating if the stopwatch has finished running.\n- `currentDays`: a number indicating the current value of the days on the stopwatch.\n- `currentHours`: a number indicating the current value of the hours on the stopwatch.\n- `currentMinutes`: a number indicating the current value of the minutes on the stopwatch.\n- `currentSeconds`: a number indicating the current value of the seconds on the stopwatch.\n- `elapsedSeconds`: a number indicating the total elapsed time, calculated in seconds, since the stopwatch started.\n- `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.\n- `remainingTime`: analogous to the `current` object, this object holds the remaining time in both formats:\n  - `withLeadingZero`: a string indicating the remaining time with leading zeroes. If `endTime` is not specified, it will always be 00:00:00:00.\n  - `withoutLeadingZero`: a string indicating the remaining time without leading zeroes. If `endTime` is not specified, it will always be 0:0:0:0.\n- `pause`: a function that, when called, will pause the stopwatch.\n- `play`: a function that, when called, will resume (or start) the stopwatch.\n- `reset`: a function that, when called, will reset the stopwatch.\n- `togglePause`: a function that, when called, will toggle between pausing and playing the stopwatch.\n\nExample:\n\n```tsx\nimport { useStopwatch } from \"final-countdown-js\";\n\nconst ReactCounter = () =\u003e {\n  const {\n    current,\n    remainingTime,\n    currentDays,\n    currentHours,\n    currentMinutes,\n    currentSeconds,\n    elapsedSeconds,\n    remainingSeconds,\n    isPaused,\n    isOver,\n    pause,\n    play,\n    reset,\n    togglePause,\n  } = useStopwatch({\n    endTime: \"00:00:00:10\",\n    startPaused: true,\n    separator: \"-\",\n    onFinish: () =\u003e console.log(\"Stopwatch ended\"),\n  });\n\n  return (\n    \u003cdiv\u003e\n      \u003cp\u003eStopwatch value: {current.withLeadingZero}\u003c/p\u003e\n      \u003cp\u003eStopwatch value: {current.withoutLeadingZero}\u003c/p\u003e\n      \u003cp\u003eRemaining time: {remainingTime.withLeadingZero}\u003c/p\u003e\n      \u003cp\u003eRemaining time: {remainingTime.withoutLeadingZero}\u003c/p\u003e\n      \u003cp\u003eDays: {currentDays}\u003c/p\u003e\n      \u003cp\u003eHours: {currentHours}\u003c/p\u003e\n      \u003cp\u003eMinutes: {currentMinutes}\u003c/p\u003e\n      \u003cp\u003eSeconds: {currentSeconds}\u003c/p\u003e\n      \u003cp\u003eElapsed seconds: {elapsedSeconds}\u003c/p\u003e\n      \u003cp\u003eRemaining seconds: {remainingSeconds}\u003c/p\u003e\n      \u003cp\u003eIs the counter paused? {isPaused ? \"Yes\" : \"No\"}\u003c/p\u003e\n      \u003cp\u003eHas the counter over? {isOver ? \"Yes\" : \"No\"}\u003c/p\u003e\n      \u003cbutton onClick={pause}\u003ePause\u003c/button\u003e\n      \u003cbutton onClick={play}\u003ePlay\u003c/button\u003e\n      \u003cbutton onClick={reset}\u003eReset\u003c/button\u003e\n      \u003cbutton onClick={togglePause}\u003eToggle Pause\u003c/button\u003e\n    \u003c/div\u003e\n  );\n};\n\nexport default ReactCounter;\n```\n\n### useTimer\n\nThe useTimer hook provides timer functionality.\n\nIt takes two arguments:\n\n- `startTime` (string): specifies the time at which the timer will start. It must be in `dd:hh:mm:ss` format.\n- `options`(optional object): the options for the timer.\n  - `startPaused` (optional boolean): determines whether the timer should start in a paused state. Defaults to false.\n  - `onFinish` (optional function): a function that will be called when the timer reaches the final value.\n  - `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.\n\nIt returns an object with the following props:\n\n- `current`: an object holding the current time of the timer in both leading zero and non-leading zero formats. This object has two properties:\n  - `withLeadingZero`: a string indicating the current time of the timer with leading zeroes where necessary.\n  - `withoutLeadingZero`: a string indicating the current time of the timer without leading zeros.\n- `isPaused`: a boolean value indicating if the timer is currently paused.\n- `isOver`: a boolean value indicating if the timer has finished running.\n- `currentDays`: a number indicating the current value of the days on the timer.\n- `currentHours`: a number indicating the current value of the hours on the timer.\n- `currentMinutes`: a number indicating the current value of the minutes on the timer.\n- `currentSeconds`: a number indicating the current value of the seconds on the timer.\n- `elapsedSeconds`: a number indicating the total elapsed time, calculated in seconds, since the timer started.\n- `remainingSeconds`: a number indicating the total remaining time, calculated in seconds, until the timer reaches the initially set time.\n- `elapsedTime`: analogous to the `current` object, this object holds the elapsed time in both formats:\n  - `withLeadingZero`: a string indicating the elapsed time with leading zeroes.\n  - `withoutLeadingZero`: a string indicating the elapsed time without leading zeroes.\n- `pause`: a function that, when called, will pause the timer.\n- `play`: a function that, when called, will resume (or start) the timer.\n- `reset`: a function that, when called, will reset the timer.\n- `togglePause`: a function that, when called, will toggle between pausing and playing the timer.\n\nExample:\n\n```tsx\nimport { useTimer } from \"final-countdown-js\";\n\nconst ReactCounter = () =\u003e {\n  const {\n    current,\n    elapsedTime,\n    currentDays,\n    currentHours,\n    currentMinutes,\n    currentSeconds,\n    elapsedSeconds,\n    remainingSeconds,\n    isPaused,\n    isOver,\n    pause,\n    play,\n    reset,\n    togglePause,\n  } = useTimer(\"00:00:00:10\", {\n    startPaused: true,\n    separator: \"-\",\n    onFinish: () =\u003e console.log(\"Timer ended\"),\n  });\n\n  return (\n    \u003cdiv\u003e\n      \u003cp\u003eTimer value: {current.withLeadingZero}\u003c/p\u003e\n      \u003cp\u003eTimer value: {current.withoutLeadingZero}\u003c/p\u003e\n      \u003cp\u003eElapsed time: {elapsedTime.withLeadingZero}\u003c/p\u003e\n      \u003cp\u003eElapsed time: {elapsedTime.withoutLeadingZero}\u003c/p\u003e\n      \u003cp\u003eDays: {currentDays}\u003c/p\u003e\n      \u003cp\u003eHours: {currentHours}\u003c/p\u003e\n      \u003cp\u003eMinutes: {currentMinutes}\u003c/p\u003e\n      \u003cp\u003eSeconds: {currentSeconds}\u003c/p\u003e\n      \u003cp\u003eElapsed seconds: {elapsedSeconds}\u003c/p\u003e\n      \u003cp\u003eRemaining seconds: {remainingSeconds}\u003c/p\u003e\n      \u003cp\u003eIs the counter paused? {isPaused ? \"Yes\" : \"No\"}\u003c/p\u003e\n      \u003cp\u003eHas the counter over? {isOver ? \"Yes\" : \"No\"}\u003c/p\u003e\n      \u003cbutton onClick={pause}\u003ePause\u003c/button\u003e\n      \u003cbutton onClick={play}\u003ePlay\u003c/button\u003e\n      \u003cbutton onClick={reset}\u003eReset\u003c/button\u003e\n      \u003cbutton onClick={togglePause}\u003eToggle Pause\u003c/button\u003e\n    \u003c/div\u003e\n  );\n};\n\nexport default ReactCounter;\n```\n\n## Contributions\n\nIf 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.\n\n## Support\n\nDon't forget to leave a star and [a review on Product Hunt!](https://www.producthunt.com/products/final-countdown-js/reviews/new)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdlcastillop%2Ffinal-countdown-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdlcastillop%2Ffinal-countdown-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdlcastillop%2Ffinal-countdown-js/lists"}