https://github.com/bradgarropy/use-countdown
⏳ useCountdown hook
https://github.com/bradgarropy/use-countdown
countdown react react-hook typescript
Last synced: about 2 months ago
JSON representation
⏳ useCountdown hook
- Host: GitHub
- URL: https://github.com/bradgarropy/use-countdown
- Owner: bradgarropy
- License: mit
- Created: 2021-01-27T05:29:05.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2024-03-02T21:20:45.000Z (over 1 year ago)
- Last Synced: 2025-04-02T07:57:17.056Z (6 months ago)
- Topics: countdown, react, react-hook, typescript
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/@bradgarropy/use-countdown
- Size: 641 KB
- Stars: 92
- Watchers: 2
- Forks: 12
- Open Issues: 2
-
Metadata Files:
- Readme: readme.md
- Contributing: contributing.md
- License: license
Awesome Lists containing this project
README
# ⏳ useCountdown hook
[![version][version-badge]][npm]
[![downloads][downloads-badge]][npm]
[![size][size-badge]][bundlephobia]
[![github actions][github-actions-badge]][github-actions]
[![codecov][codecov-badge]][codecov]
[![typescript][typescript-badge]][typescript]
[![contributing][contributing-badge]][contributing]
[![contributors][contributors-badge]][contributors]
[![discord][discord-badge]][discord]
_[React][react] hook countdown timer. As seen on my [Twitch][twitch] streams._
## 📦 Installation
This package is hosted on [npm][npm].
```bash
npm install @bradgarropy/use-countdown
```
## 🥑 Usage
In 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.
```typescript
import useCountdown from "@bradgarropy/use-countdown"
const App = () => {
const countdown = useCountdown({
minutes: 1,
seconds: 30,
format: "mm:ss",
autoStart: true,
onCompleted: () => console.log("onCompleted"),
})
console.log(countdown)
// {minutes: 1, seconds: 30, formatted: "01:30", ...}
// {minutes: 1, seconds: 29, formatted: "01:29", ...}
// {minutes: 1, seconds: 28, formatted: "01:28", ...}
// ...
// {minutes: 0, seconds: 0, formatted: "00:00", ...}
// onCompleted()
}
```
## 📖 API Reference
### `useCountdown({minutes, seconds})`
| Name | Required | Default | Example | Description |
| :------------ | :------: | :---------: | :--------: | :--------------------------------------------------- |
| `minutes` | `false` | `0` | `1` | Countdown minutes. |
| `seconds` | `false` | `0` | `30` | Countdown seconds. |
| `format` | `false` | `mm:ss` | `mm:ss:SS` | Format string ([reference][format]). |
| `autoStart` | `false` | `false` | `true` | Whether or not to automatically start the countdown. |
| `onCompleted` | `false` | `undefined` | `function` | Function to call when countdown completes. |
Starts 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.
The `format` parameter is a [`date-fns`][date-fns] format string.
If provided, the `onCompleted` function will be called when the countdown completes.
Here are some examples of how to call `useCountdown`.
```typescript
const countdown = useCountdown({
minutes: 1,
seconds: 30,
format: "mm:ss:SS",
autoStart: true,
onCompleted: () => console.log("onCompleted"),
})
const countdown = useCountdown({
minutes: 5,
onCompleted: () => console.log("onCompleted"),
})
const countdown = useCountdown({seconds: 10, format: "mm:ss:SS"})
```
The return object is updated every second until the countdown timer ends.
| Name | Type | Example | Description |
| :----------- | :--------: | :--------: | :------------------------------------------------------------------------ |
| `minutes` | `number` | `1` | Remaining minutes. |
| `seconds` | `number` | `30` | Remaining seconds. |
| `formatted` | `string` | `01:30` | Formatted remaining time. |
| `isActive` | `boolean` | `true` | Indicates that the countdown is active, either running or paused. |
| `isInactive` | `boolean` | `false` | Indicates that the countdown is inactive, and has finished counting down. |
| `isRunning` | `boolean` | `true` | Indicates that the countdown is running. |
| `isPaused` | `boolean` | `false` | Indicates that the countdown is paused. |
| `pause` | `function` | `function` | Pauses the countdown. |
| `resume` | `function` | `function` | Resumes the countdown. |
| `reset` | `function` | `function` | Resets the countdown. |
Here is an example of the returned object.
```typescript
{
minutes: 1,
seconds: 30,
formatted: "01:30",
isActive: true,
isInactive: false,
isRunning: true,
isPaused: false,
pause: () => void,
resume: () => void,
reset: (time?: Time) => void,
}
```
## ❔ Questions
🐛 report bugs by filing [issues][issues]
📢 provide feedback with [issues][issues] or on [twitter][twitter]
🙋🏼♂️ use my [ama][ama] or [twitter][twitter] to ask any other questions
## ✨ Contributors
Brad Garropy
💻 📖 ⚠️ 🚇
Matthew Scholta
💻 📖
James Q Quick
🤔 📓
Steven Hofheins
📝 ✅
Jack Reiker
🤔 📓
Mehdi Makhloufi
🤔 📓
Daniel Badir
🐛 🤔 📓
Florin Cosmin
💻
Nick DiMatteo
🐛
Jimmy Longley
🤔
Nuno Fonseca
🤔
Nathan Arthur
🐛
msopacua
🐛 💻
[issues]: https://github.com/bradgarropy/use-countdown/issues
[ama]: https://bradgarropy.com/ama
[twitter]: https://twitter.com/bradgarropy
[react]: https://reactjs.org
[twitch]: https://twitch.tv/bradgarropy
[npm]: https://www.npmjs.com/package/@bradgarropy/use-countdown
[hooks]: https://reactjs.org/docs/hooks-intro.html
[bundlephobia]: https://bundlephobia.com/result?p=@bradgarropy/use-countdown
[github-actions]: https://github.com/bradgarropy/use-countdown/actions
[codecov]: https://app.codecov.io/gh/bradgarropy/use-countdown
[typescript]: https://www.typescriptlang.org/dt/search?search=%40bradgarropy%2Fuse-countdown
[contributing]: https://github.com/bradgarropy/use-countdown/blob/master/contributing.md
[contributors]: #-Contributors
[discord]: https://bradgarropy.com/discord
[version-badge]: https://img.shields.io/npm/v/@bradgarropy/use-countdown.svg?style=flat-square
[downloads-badge]: https://img.shields.io/npm/dt/@bradgarropy/use-countdown?style=flat-square
[size-badge]: https://img.shields.io/bundlephobia/minzip/@bradgarropy/use-countdown?style=flat-square
[github-actions-badge]: https://img.shields.io/github/workflow/status/bradgarropy/use-countdown/%F0%9F%9A%80%20release?style=flat-square
[codecov-badge]: https://img.shields.io/codecov/c/github/bradgarropy/use-countdown?style=flat-square
[typescript-badge]: https://img.shields.io/npm/types/@bradgarropy/use-countdown?style=flat-square
[contributing-badge]: https://img.shields.io/badge/PRs-welcome-success?style=flat-square
[contributors-badge]: https://img.shields.io/github/all-contributors/bradgarropy/use-countdown?style=flat-square
[discord-badge]: https://img.shields.io/discord/748196643140010015?style=flat-square
[date-fns]: https://date-fns.org
[format]: https://date-fns.org/docs/format