## Table of Contents
- [Documentation](#documentation)
- [Overview](#overview)
- [Features include:](#features-include)
- [🆕 New In Version 3](#-new-in-version-3)
- [Donate](#donate)
- [Table of Contents](#table-of-contents)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Repeating Timer](#repeating-timer)
- [One-Time Delay](#one-time-delay)
- [Stopwatch](#stopwatch)
- [Momentary Boolean](#momentary-boolean)
- [Other Usage](#other-usage)
- [TypeScript](#typescript)
- [Icon Attribution](#icon-attribution)
- [Contributing](#contributing)
- [⭐ Found It Helpful? Star It!](#-found-it-helpful-star-it)
- [License](#license)
## Installation
```
npm i react-use-precision-timer
```
## Quick Start
### Repeating Timer
```jsx
import { useTimer } from "react-use-precision-timer";
```
In your function component:
```jsx
const callback = React.useCallback(() => console.log('Boom'), []);
// The callback will be called every 1000 milliseconds.
const timer = useTimer({ delay: 1000 }, callback);
```
In a handler or effect:
```jsx
timer.start();
```
The following functions can be used to control the [Timer](https://justinmahar.github.io/react-use-precision-timer/?path=/story/docs-usetimer--docs#timer):
- `timer.start()` - Start the timer. If already started, will restart the timer. You can optionally pass a start time in Unix epoch milliseconds.
- `timer.stop()` - Stop the timer.
- `timer.pause()` - Pause the timer.
- `timer.resume()` - Resume the timer.
Refer to [Timer](https://justinmahar.github.io/react-use-precision-timer/?path=/story/docs-usetimer--docs#timer) for all available functions, including getters for elapsed times.
### One-Time Delay
If you'd like to run a callback after a one-time delay, use the helper hook [useDelay](https://justinmahar.github.io/react-use-precision-timer/?path=/story/docs-usedelay--docs):
```jsx
import { useDelay } from 'react-use-precision-timer';
```
In your function component:
```jsx
const callback = React.useCallback(() => console.log('Boom'), []);
// Will call once after 1000ms.
const onceTimer = useDelay(1000, callback);
```
In a handler or effect:
```jsx
onceTimer.start();
```
This will call the callback after the provided 1000 millisecond delay only once.
### Stopwatch
The timer also functions as a stopwatch when no delay is provided. You can use the helper hook [useStopwatch](https://justinmahar.github.io/react-use-precision-timer/?path=/story/docs-usestopwatch--docs):
```jsx
import { useStopwatch } from "react-use-precision-timer";
```
```jsx
const stopwatch = useStopwatch();
```
Use `start()`, `stop()`, `pause()`, and `resume()` to control the stopwatch.
Stopwatch is a [Timer](https://justinmahar.github.io/react-use-precision-timer/?path=/story/docs-usetimer--docs#timer) object. Refer to Timer's getters to retrieve elapsed running time, paused time, and so forth.
Calling start while a stopwatch is already running will restart it.
### Momentary Boolean
For convenience, the [useMomentaryBool](https://justinmahar.github.io/react-use-precision-timer/?path=/story/docs-usemomentarybool--docs) hook has been included to momentarily toggle a boolean. This wraps the [useDelay](https://justinmahar.github.io/react-use-precision-timer/?path=/story/docs-usedelay--docs) hook.
This is very useful for momentary notifications, such as a copy button that shows a momentary checkmark to indicate the operation succeeded.
```jsx
import { useMomentaryBool } from 'react-use-precision-timer';
```
In your function component:
```jsx
// Toggle to true, then back to false after 1000ms.
const [value, toggle] = useMomentaryBool(false, 1000);
```
Calling `toggle()` will set the boolean to `true`, then back to `false` after a 1000 millisecond delay.
### Other Usage
See [useTimer](https://justinmahar.github.io/react-use-precision-timer/?path=/story/docs-usetimer--docs) for all other hook options and timer functions.
## TypeScript
Type definitions have been included for [TypeScript](https://www.typescriptlang.org/) support.
## Icon Attribution
Favicon by [Twemoji](https://github.com/twitter/twemoji).
## Contributing
Open source software is awesome and so are you. 😎
Feel free to submit a pull request for bugs or additions, and make sure to update tests as appropriate. If you find a mistake in the docs, send a PR! Even the smallest changes help.
For major changes, open an issue first to discuss what you'd like to change.
## ⭐ Found It Helpful? [Star It!](https://github.com/justinmahar/react-use-precision-timer/stargazers)
If you found this project helpful, let the community know by giving it a [star](https://github.com/justinmahar/react-use-precision-timer/stargazers): [👉⭐](https://github.com/justinmahar/react-use-precision-timer/stargazers)
Want to support the project? Feel free to grab me a coffee, which is my main source of fuel for development:
## License
See [LICENSE.md](https://justinmahar.github.io/react-use-precision-timer/?path=/docs/license--docs).