{"id":16629029,"url":"https://github.com/bradgarropy/use-countdown","last_synced_at":"2025-08-16T21:08:04.061Z","repository":{"id":37018879,"uuid":"333314139","full_name":"bradgarropy/use-countdown","owner":"bradgarropy","description":"⏳ useCountdown hook","archived":false,"fork":false,"pushed_at":"2024-03-02T21:20:45.000Z","size":656,"stargazers_count":92,"open_issues_count":2,"forks_count":12,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-02T07:57:17.056Z","etag":null,"topics":["countdown","react","react-hook","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@bradgarropy/use-countdown","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/bradgarropy.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":"contributing.md","funding":null,"license":"license","code_of_conduct":null,"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}},"created_at":"2021-01-27T05:29:05.000Z","updated_at":"2025-01-30T15:14:06.000Z","dependencies_parsed_at":"2024-06-18T21:22:41.639Z","dependency_job_id":"8d5bf9d9-2b9e-4382-95b5-3a635a4ed518","html_url":"https://github.com/bradgarropy/use-countdown","commit_stats":{"total_commits":32,"total_committers":5,"mean_commits":6.4,"dds":0.375,"last_synced_commit":"0f865eaf0564de27dadf1f5e03df44a013f4a2b1"},"previous_names":[],"tags_count":23,"template":false,"template_full_name":"bradgarropy/react-library-starter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bradgarropy%2Fuse-countdown","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bradgarropy%2Fuse-countdown/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bradgarropy%2Fuse-countdown/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bradgarropy%2Fuse-countdown/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bradgarropy","download_url":"https://codeload.github.com/bradgarropy/use-countdown/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248054194,"owners_count":21039952,"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":["countdown","react","react-hook","typescript"],"created_at":"2024-10-12T04:39:05.083Z","updated_at":"2025-04-09T14:09:41.462Z","avatar_url":"https://github.com/bradgarropy.png","language":"TypeScript","readme":"# ⏳ useCountdown hook\n\n[![version][version-badge]][npm]\n[![downloads][downloads-badge]][npm]\n[![size][size-badge]][bundlephobia]\n[![github actions][github-actions-badge]][github-actions]\n[![codecov][codecov-badge]][codecov]\n[![typescript][typescript-badge]][typescript]\n[![contributing][contributing-badge]][contributing]\n[![contributors][contributors-badge]][contributors]\n[![discord][discord-badge]][discord]\n\n_[React][react] hook countdown timer. As seen on my [Twitch][twitch] streams._\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://www.npmjs.com/package/@bradgarropy/use-countdown\"\u003e\n        \u003cimg alt=\"next link\" src=\"./images/github.png\" width=\"500\"\u003e\n    \u003c/a\u003e\n\u003c/p\u003e\n\n## 📦 Installation\n\nThis package is hosted on [npm][npm].\n\n```bash\nnpm install @bradgarropy/use-countdown\n```\n\n## 🥑 Usage\n\nIn any React component, import `useCountdown`, then call it like any other [hook][hooks]. The returned `countdown` value will update every second with the remaining time.\n\n```typescript\nimport useCountdown from \"@bradgarropy/use-countdown\"\n\nconst App = () =\u003e {\n    const countdown = useCountdown({\n        minutes: 1,\n        seconds: 30,\n        format: \"mm:ss\",\n        autoStart: true,\n        onCompleted: () =\u003e console.log(\"onCompleted\"),\n    })\n\n    console.log(countdown)\n\n    // {minutes: 1, seconds: 30, formatted: \"01:30\", ...}\n    // {minutes: 1, seconds: 29, formatted: \"01:29\", ...}\n    // {minutes: 1, seconds: 28, formatted: \"01:28\", ...}\n    // ...\n    // {minutes: 0, seconds: 0, formatted: \"00:00\", ...}\n    // onCompleted()\n}\n```\n\n## 📖 API Reference\n\n### `useCountdown({minutes, seconds})`\n\n| Name          | Required |   Default   |  Example   | Description                                          |\n| :------------ | :------: | :---------: | :--------: | :--------------------------------------------------- |\n| `minutes`     | `false`  |     `0`     |    `1`     | Countdown minutes.                                   |\n| `seconds`     | `false`  |     `0`     |    `30`    | Countdown seconds.                                   |\n| `format`      | `false`  |   `mm:ss`   | `mm:ss:SS` | Format string ([reference][format]).                 |\n| `autoStart`   | `false`  |   `false`   |   `true`   | Whether or not to automatically start the countdown. |\n| `onCompleted` | `false`  | `undefined` | `function` | Function to call when countdown completes.           |\n\nStarts 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.\n\nThe `format` parameter is a [`date-fns`][date-fns] format string.\n\nIf provided, the `onCompleted` function will be called when the countdown completes.\n\nHere are some examples of how to call `useCountdown`.\n\n```typescript\nconst countdown = useCountdown({\n    minutes: 1,\n    seconds: 30,\n    format: \"mm:ss:SS\",\n    autoStart: true,\n    onCompleted: () =\u003e console.log(\"onCompleted\"),\n})\n\nconst countdown = useCountdown({\n    minutes: 5,\n    onCompleted: () =\u003e console.log(\"onCompleted\"),\n})\n\nconst countdown = useCountdown({seconds: 10, format: \"mm:ss:SS\"})\n```\n\nThe return object is updated every second until the countdown timer ends.\n\n| Name         |    Type    |  Example   | Description                                                               |\n| :----------- | :--------: | :--------: | :------------------------------------------------------------------------ |\n| `minutes`    |  `number`  |    `1`     | Remaining minutes.                                                        |\n| `seconds`    |  `number`  |    `30`    | Remaining seconds.                                                        |\n| `formatted`  |  `string`  |  `01:30`   | Formatted remaining time.                                                 |\n| `isActive`   | `boolean`  |   `true`   | Indicates that the countdown is active, either running or paused.         |\n| `isInactive` | `boolean`  |  `false`   | Indicates that the countdown is inactive, and has finished counting down. |\n| `isRunning`  | `boolean`  |   `true`   | Indicates that the countdown is running.                                  |\n| `isPaused`   | `boolean`  |  `false`   | Indicates that the countdown is paused.                                   |\n| `pause`      | `function` | `function` | Pauses the countdown.                                                     |\n| `resume`     | `function` | `function` | Resumes the countdown.                                                    |\n| `reset`      | `function` | `function` | Resets the countdown.                                                     |\n\nHere is an example of the returned object.\n\n```typescript\n{\n    minutes: 1,\n    seconds: 30,\n    formatted: \"01:30\",\n    isActive: true,\n    isInactive: false,\n    isRunning: true,\n    isPaused: false,\n    pause: () =\u003e void,\n    resume: () =\u003e void,\n    reset: (time?: Time) =\u003e void,\n}\n```\n\n## ❔ Questions\n\n🐛 report bugs by filing [issues][issues]  \n📢 provide feedback with [issues][issues] or on [twitter][twitter]  \n🙋🏼‍♂️ use my [ama][ama] or [twitter][twitter] to ask any other questions\n\n## ✨ Contributors\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --\u003e\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- markdownlint-disable --\u003e\n\u003ctable\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://bradgarropy.com\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/11336745?v=4?s=100\" width=\"100px;\" alt=\"Brad Garropy\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eBrad Garropy\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/bradgarropy/use-countdown/commits?author=bradgarropy\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/bradgarropy/use-countdown/commits?author=bradgarropy\" title=\"Documentation\"\u003e📖\u003c/a\u003e \u003ca href=\"https://github.com/bradgarropy/use-countdown/commits?author=bradgarropy\" title=\"Tests\"\u003e⚠️\u003c/a\u003e \u003ca href=\"#infra-bradgarropy\" title=\"Infrastructure (Hosting, Build-Tools, etc)\"\u003e🚇\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://www.mattscholta.com\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/545829?v=4?s=100\" width=\"100px;\" alt=\"Matthew Scholta\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eMatthew Scholta\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/bradgarropy/use-countdown/commits?author=visormatt\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/bradgarropy/use-countdown/commits?author=visormatt\" title=\"Documentation\"\u003e📖\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"http://jamesqquick.com\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/5391915?v=4?s=100\" width=\"100px;\" alt=\"James Q Quick\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eJames Q Quick\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"#ideas-jamesqquick\" title=\"Ideas, Planning, \u0026 Feedback\"\u003e🤔\u003c/a\u003e \u003ca href=\"#userTesting-jamesqquick\" title=\"User Testing\"\u003e📓\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"http://stevencreates.tech\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/37391025?v=4?s=100\" width=\"100px;\" alt=\"Steven Hofheins\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eSteven Hofheins\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"#blog-StevenCreates\" title=\"Blogposts\"\u003e📝\u003c/a\u003e \u003ca href=\"#tutorial-StevenCreates\" title=\"Tutorials\"\u003e✅\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"http://fish.solar\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/66899904?v=4?s=100\" width=\"100px;\" alt=\"Jack Reiker\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eJack Reiker\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"#ideas-rpxs\" title=\"Ideas, Planning, \u0026 Feedback\"\u003e🤔\u003c/a\u003e \u003ca href=\"#userTesting-rpxs\" title=\"User Testing\"\u003e📓\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/Mehdmhd\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/40036740?v=4?s=100\" width=\"100px;\" alt=\"Mehdi Makhloufi\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eMehdi Makhloufi\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"#ideas-Mehdmhd\" title=\"Ideas, Planning, \u0026 Feedback\"\u003e🤔\u003c/a\u003e \u003ca href=\"#userTesting-Mehdmhd\" title=\"User Testing\"\u003e📓\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/SirIsaacNeutron\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/36581033?v=4?s=100\" width=\"100px;\" alt=\"Daniel Badir\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eDaniel Badir\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/bradgarropy/use-countdown/issues?q=author%3ASirIsaacNeutron\" title=\"Bug reports\"\u003e🐛\u003c/a\u003e \u003ca href=\"#ideas-SirIsaacNeutron\" title=\"Ideas, Planning, \u0026 Feedback\"\u003e🤔\u003c/a\u003e \u003ca href=\"#userTesting-SirIsaacNeutron\" title=\"User Testing\"\u003e📓\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/bboydflo\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/2241459?v=4?s=100\" width=\"100px;\" alt=\"Florin Cosmin\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eFlorin Cosmin\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/bradgarropy/use-countdown/commits?author=bboydflo\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"http://nickdimatteo.com\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/737188?v=4?s=100\" width=\"100px;\" alt=\"Nick DiMatteo\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eNick DiMatteo\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/bradgarropy/use-countdown/issues?q=author%3Andimatteo\" title=\"Bug reports\"\u003e🐛\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"http://jimmylongley.com\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/1380097?v=4?s=100\" width=\"100px;\" alt=\"Jimmy Longley\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eJimmy Longley\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"#ideas-JLongley\" title=\"Ideas, Planning, \u0026 Feedback\"\u003e🤔\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"http://nunofonseca.net\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/5241920?v=4?s=100\" width=\"100px;\" alt=\"Nuno Fonseca\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eNuno Fonseca\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"#ideas-nfplay\" title=\"Ideas, Planning, \u0026 Feedback\"\u003e🤔\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/narthur\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/4655422?v=4?s=100\" width=\"100px;\" alt=\"Nathan Arthur\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eNathan Arthur\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/bradgarropy/use-countdown/issues?q=author%3Anarthur\" title=\"Bug reports\"\u003e🐛\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/msopacua\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/144725145?v=4?s=100\" width=\"100px;\" alt=\"msopacua\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003emsopacua\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/bradgarropy/use-countdown/issues?q=author%3Amsopacua\" title=\"Bug reports\"\u003e🐛\u003c/a\u003e \u003ca href=\"https://github.com/bradgarropy/use-countdown/commits?author=msopacua\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\n\u003c!-- markdownlint-restore --\u003e\n\u003c!-- prettier-ignore-end --\u003e\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n\n[issues]: https://github.com/bradgarropy/use-countdown/issues\n[ama]: https://bradgarropy.com/ama\n[twitter]: https://twitter.com/bradgarropy\n[react]: https://reactjs.org\n[twitch]: https://twitch.tv/bradgarropy\n[npm]: https://www.npmjs.com/package/@bradgarropy/use-countdown\n[hooks]: https://reactjs.org/docs/hooks-intro.html\n[bundlephobia]: https://bundlephobia.com/result?p=@bradgarropy/use-countdown\n[github-actions]: https://github.com/bradgarropy/use-countdown/actions\n[codecov]: https://app.codecov.io/gh/bradgarropy/use-countdown\n[typescript]: https://www.typescriptlang.org/dt/search?search=%40bradgarropy%2Fuse-countdown\n[contributing]: https://github.com/bradgarropy/use-countdown/blob/master/contributing.md\n[contributors]: #-Contributors\n[discord]: https://bradgarropy.com/discord\n[version-badge]: https://img.shields.io/npm/v/@bradgarropy/use-countdown.svg?style=flat-square\n[downloads-badge]: https://img.shields.io/npm/dt/@bradgarropy/use-countdown?style=flat-square\n[size-badge]: https://img.shields.io/bundlephobia/minzip/@bradgarropy/use-countdown?style=flat-square\n[github-actions-badge]: https://img.shields.io/github/workflow/status/bradgarropy/use-countdown/%F0%9F%9A%80%20release?style=flat-square\n[codecov-badge]: https://img.shields.io/codecov/c/github/bradgarropy/use-countdown?style=flat-square\n[typescript-badge]: https://img.shields.io/npm/types/@bradgarropy/use-countdown?style=flat-square\n[contributing-badge]: https://img.shields.io/badge/PRs-welcome-success?style=flat-square\n[contributors-badge]: https://img.shields.io/github/all-contributors/bradgarropy/use-countdown?style=flat-square\n[discord-badge]: https://img.shields.io/discord/748196643140010015?style=flat-square\n[date-fns]: https://date-fns.org\n[format]: https://date-fns.org/docs/format\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbradgarropy%2Fuse-countdown","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbradgarropy%2Fuse-countdown","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbradgarropy%2Fuse-countdown/lists"}