# use-pretty-elapsed-timer

> use-pretty-elapsed-timer is a custom React hook that provides a timer/stopwatch functionality. It takes a time format string and returns human-readable time strings. The hook also returns start, stop function, and running status. It can take an optional a

Latest version **1.1.1** (published 2024-03-11) · MIT license · 0 weekly downloads

## Install

```sh
npm install use-pretty-elapsed-timer
pnpm add use-pretty-elapsed-timer
yarn add use-pretty-elapsed-timer
bun add use-pretty-elapsed-timer
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.1.1 |
| Published | 2024-03-11 |
| First published | 2023-05-20 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 11.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | larebsyed |
| Maintainers | larebsyed |
| Keywords | React, custom hook, timer, stopwatch, time logic, state management, requestAnimationFrame, elapsed time, auto-ticks, time format string, human-readable time strings, start function, stop function, running status, display time in human-readable formats, maximum time in seconds |

## Links

- npm: https://www.npmjs.com/package/use-pretty-elapsed-timer
- Repository: https://github.com/larebsyed/use-pretty-elapsed-time
- npm.io page: https://npm.io/package/use-pretty-elapsed-timer

## Dependencies (2)

- [react](https://npm.io/package/react.md) ^18.2.0
- [@types/react](https://npm.io/package/@types/react.md) ^18.2.6

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 1.1.1 (latest) — 2024-03-11
- 1.1.0 — 2024-03-11
- 1.0.5 — 2023-08-15
- 1.0.4 — 2023-08-15
- 1.0.3 — 2023-05-20
- 1.0.2 — 2023-05-20
- 1.0.1 — 2023-05-20
- 1.0.0 — 2023-05-20

## README

# use-pretty-elapsed-timer
The `use-pretty-elapsed-timer` package is a custom React hook that handles timers, specifically a stopwatch, and time logic/state in a React component. It uses `requestAnimationFrame` to measure elapsed time and auto-ticks every second. The hook takes a time format string as an argument and returns human-readable time strings. It also returns start, stop functions, and running status. An optional argument for the maximum time in seconds can also be passed. The use case of this package related to displaying time in human readable formats efficiently.

## Description
The `use-pretty-elapsed-timer` hook is a timer function that auto-ticks every second. It provides the following functionalities:
- Start the timer
- Stop the timer
- Check if the timer is running
- Get the elapsed time in human-readable format
## Installation
To install use-pretty-elapsed-timer, run the following command:
```sh
npm install use-pretty-elapsed-timer
```
## Usage
```jsx
import usePrettyElapsedTimer from 'use-pretty-elapsed-timer';

function App() {
  const { elapsedTime, start, stop, running } = usePrettyElapsedTimer('hh:mm:ss', 60);

  return (
    <div>
      <h1>{elapsedTime}</h1>
      <button onClick={start}>Start</button>
      <button onClick={stop}>Stop</button>
      <p>{running ? 'Timer is running' : 'Timer is not running'}</p>
    </div>
  );
}
```
## Parameters
The use-pretty-elapsed-timer hook takes two parameters:
1. format: A string that specifies the format of the elapsed time. The format string can contain any combination of hh, mm, and ss to represent hours, minutes, and seconds respectively.
2. maxTime: An optional number that specifies the maximum time in seconds. Once the elapsed time reaches this value, the timer will stop automatically.
## Return Values
The use-pretty-elapsed-timer hook returns an object with the following properties:
1. elapsedTime: A string that represents the elapsed time in the specified format.
2. start: A function that starts the timer.
3. stop: A function that stops the timer.
4. isRunning: A boolean that indicates whether the timer is currently running or not.
## Examples
### Example 1: Basic Usage
```jsx
import usePrettyElapsedTimer from 'use-pretty-elapsed-timer';

function App() {
  const { elapsedTime, start, stop, isRunning } = usePrettyElapsedTimer('hh:mm:ss');

  return (
    <div>
      <h1>{elapsedTime}</h1>
      <button onClick={start}>Start</button>
      <button onClick={stop}>Stop</button>
      <p>{isRunning ? 'Timer is running' : 'Timer is not running'}</p>
    </div>
  );
}
```
### Example 2: With Maximum Time
```jsx
import usePrettyElapsedTimer from 'use-pretty-elapsed-timer';

function App() {
  const { elapsedTime, start, stop, running } = usePrettyElapsedTimer('mm:ss', 120);

  return (
    <div>
      <h1>{elapsedTime}</h1>
      <button onClick={start}>Start</button>
      <button onClick={stop}>Stop</button>
      <p>{running ? 'Timer is running' : 'Timer is not running'}</p>
    </div>
  );
}
```
In this example, the maximum time is set to 120 seconds (2 minutes). Once the elapsed time reaches this value, the timer will stop automatically.
## License
This package is licensed under the [MIT License](https://opensource.org/licenses/MIT).

---
_Source: https://npm.io/package/use-pretty-elapsed-timer · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._