# @mzaleski/use-timer

> React hook that returns a timer's remaining span as a formatted time string, e.g. 65 -> '1:05', as well as numerically.

Latest version **1.2.3** (published 2023-02-22) · MIT license · 0 weekly downloads

## Install

```sh
npm install @mzaleski/use-timer
pnpm add @mzaleski/use-timer
yarn add @mzaleski/use-timer
bun add @mzaleski/use-timer
```

## Health

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

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.2.3 |
| Published | 2023-02-22 |
| First published | 2022-12-12 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 14.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Maximilien Zaleski |
| Maintainers | maxzaleski |
| Keywords | react-hook, use-timer, react-timer |

## Links

- npm: https://www.npmjs.com/package/@mzaleski/use-timer
- Repository: https://github.com/maxzaleski/useTimer
- Homepage: https://github.com/maxzaleski/useTimer#readme
- Issues: https://github.com/maxzaleski/useTimer/issues
- npm.io page: https://npm.io/package/@mzaleski/use-timer

## 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.2.3 (latest) — 2023-02-22
- 1.2.2 — 2022-12-16
- 1.2.1 — 2022-12-13
- 1.2.0 — 2022-12-13
- 1.1.1 — 2022-12-12
- 1.1.0 — 2022-12-12
- 1.0.2 — 2022-12-12

## README

# use-timer

React hook that returns a timer's remaining span as a formatted time string, e.g. 65 -> "01:05", as well as numerically.

## Table of Contents

- [use-timer](#use-timer)
  - [Table of Contents](#table-of-contents)
  - [Installation](#installation)
  - [Usage](#usage)
    - [Configuration](#configuration)
    - [Properties](#properties)
  - [TypeScript Support](#typescript-support)
  - [License](#license)

---

## Installation 

Install through your package manager of choice (npm, yarn, etc.)

```
npm -i @mzaleski/use-timer
```

```
yarn add @mzaleski/use-timer
```

## Usage

```jsx
import { useTimer } from '@mzaleski/use-timer';

function Component(props) {
  const { timeRemaining, secondsRemaining, setFreeze, resetTimer } = useTimer(65, false,                               
    () => console.log('Timer finished!') 
  );

  return (
    <div>
      <p>Time remaining: {timeRemaining}</p>
      <p>Seconds remaining: {secondsRemaining}</p>
      <button onClick={() => setFreeze(true)}>Freeze</button>
      <button onClick={() => setFreeze(false)}>Unfreeze</button>
      <button onClick={() => resetTimer()}>Reset</button>
    </div>
  );
}
```

### Configuration

The hook's configuration options are as follows:

| Name             | Type     | Description                                |
| ---------------- | -------- | ------------------------------------------ |
| `initialSeconds` | Number   | Initial (remaining) time in seconds        |
| `initialFreeze`  | Boolean  | Initial freeze state                       |
| `onCompleted`    | Function | A hook called once the timer has completed |

### Properties

The hook returns the following properties:

| Name               | Type     | Description                                                                                                              |
| ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------ |
| `timeRemaining`    | String   | The time remaining as a formatted string, e.g. "01:05"                                                                   |
| `secondsRemaining` | Number   | The time remaining as seconds                                                                                            |
| `isFrozen`         | Boolean  | Whether the timer is frozen                                                                                              |
| `setFreeze`        | Function | A setter for the timer's freeze state                                                                                    |
| `resetTimer`       | Function | A function to force-reset the timer – takes the `freeze` parameter which dictates whether to start the timer upon reset. |

## TypeScript Support 

You will find a collection of typings bundled with the package.

## License

[MIT License](LICENSE) (c) 2022 Maximilien Zaleski

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