https://github.com/bradgarropy/use-timer
⏱ useTimer hook
https://github.com/bradgarropy/use-timer
eslint jest prettier react react-hook stopwatch timer typescript
Last synced: 3 months ago
JSON representation
⏱ useTimer hook
- Host: GitHub
- URL: https://github.com/bradgarropy/use-timer
- Owner: bradgarropy
- License: mit
- Created: 2021-07-21T02:51:48.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2021-09-19T19:13:44.000Z (almost 5 years ago)
- Last Synced: 2025-02-18T05:37:04.605Z (over 1 year ago)
- Topics: eslint, jest, prettier, react, react-hook, stopwatch, timer, typescript
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/@bradgarropy/use-timer
- Size: 343 KB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
- Contributing: contributing.md
- License: license
Awesome Lists containing this project
README
# ⏱ useTimer
[![version][version-badge]][npm]
[![downloads][downloads-badge]][npm]
[![size][size-badge]][bundlephobia]
[![github actions][github-actions-badge]][github-actions]
[![coverage][codecov-badge]][codecov]
[![typescript][typescript-badge]][typescript]
[![contributing][contributing-badge]][contributing]
[![contributors][contributors-badge]][contributors]
[![discord][discord-badge]][discord]
_[`React`][react] hook implementation of a stopwatch. Featured in [MURPHY][murphy]._
## 📦 Installation
This package is hosted on [`npm`][npm].
```bash
npm install @bradgarropy/use-timer
```
## 🥑 Usage
Import the `useTimer` hook in any React component, then call it to receive a `timer` that holds the state and functions which implement a stopwatch.
```javascript
import useTimer from "@bradgarropy/use-timer"
const App = () => {
const timer = useTimer()
timer.start()
timer.lap()
timer.lap()
timer.lap()
timer.stop()
console.log(timer.elapsedTime)
// 3000
console.log(timer.laps)
// [
// {start: 0, end: 1000, time: 1000},
// {start: 1000, end: 2000, time: 1000},
// {start: 2000, end: 3000, time: 1000}
// ]
timer.reset()
}
```
## 📖 API Reference
### `useTimer()`
Instantiates a `timer`, which updates with the latest values. No arguments are required. The hook returns an object with everything needed to implement a stopwatch.
| Name | Type | Example | Description |
| :------------ | :--------: | :--------: | :------------------------------------------------------------- |
| `isActive` | `boolean` | `false` | Indicates that the timer is active, either running or paused. |
| `isInactive` | `boolean` | `true` | Indicates that the timer is inactive, and hasn't been started. |
| `isRunning` | `boolean` | `false` | Indicates if the timer is running. |
| `isPaused` | `boolean` | `false` | Indicates if the timer is paused. |
| `elapsedTime` | `number` | `0` | Total time in milliseconds. |
| `laps` | `object` | `[]` | Array of [`laps`][laps]. |
| `start` | `function` | `function` | Starts the timer. |
| `stop` | `function` | `function` | Pauses the timer. |
| `reset` | `function` | `function` | Resets the timer. |
| `lap` | `function` | `function` | Adds a new lap. |
The `elapsedTime` is expressed in milliseconds, and has a resolution of `10ms`.
Each of the control functions are ignored in certain situations.
- `start` does nothing if the timer is already running.
- `stop` does nothing if the timer is already paused.
- `reset` does nothing if the timer is inactive.
- `lap` does nothing if the timer is paused.
## ❔ 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
💻 📖 ⚠️ 🚇
Sam Apter
🐛 📖
[codecov]: https://app.codecov.io/gh/bradgarropy/use-timer
[contributing]: https://github.com/bradgarropy/use-timer/blob/master/contributing.md
[contributors]: #-contributors
[npm]: https://www.npmjs.com/package/@bradgarropy/use-timer
[codecov-badge]: https://img.shields.io/codecov/c/github/bradgarropy/use-timer?style=flat-square
[version-badge]: https://img.shields.io/npm/v/@bradgarropy/use-timer.svg?style=flat-square
[downloads-badge]: https://img.shields.io/npm/dt/@bradgarropy/use-timer?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-timer?style=flat-square
[issues]: https://github.com/bradgarropy/use-timer/issues
[twitter]: https://twitter.com/bradgarropy
[ama]: https://bradgarropy.com/ama
[bundlephobia]: https://bundlephobia.com/result?p=@bradgarropy/use-timer
[size-badge]: https://img.shields.io/bundlephobia/minzip/@bradgarropy/use-timer?style=flat-square
[github-actions]: https://github.com/bradgarropy/use-timer/actions
[github-actions-badge]: https://img.shields.io/github/workflow/status/bradgarropy/use-timer/%F0%9F%9A%80%20release?style=flat-square
[typescript]: https://www.typescriptlang.org/dt/search?search=%40bradgarropy%2Fuse-timer
[typescript-badge]: https://img.shields.io/npm/types/@bradgarropy/use-timer?style=flat-square
[discord]: https://bradgarropy.com/discord
[discord-badge]: https://img.shields.io/discord/748196643140010015?style=flat-square
[react]: https://reactjs.org
[murphy]: https://murphy.bradgarropy.com
[laps]: https://github.com/bradgarropy/use-timer/blob/master/src/useTimer.tsx#L16-L20