# use-timer

> A timer hook for React

Latest version **2.0.1** (published 2020-10-23) · ISC license · 0 weekly downloads

## Install

```sh
npm install use-timer
pnpm add use-timer
yarn add use-timer
bun add 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 | 2.0.1 |
| Published | 2020-10-23 |
| First published | 2019-02-28 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 13.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 206 |
| Author | Thibault Boursier |
| Maintainers | thibaultboursier |
| Keywords | react, react-hook, react-hooks, timer |

## Links

- npm: https://www.npmjs.com/package/use-timer
- Repository: https://github.com/thibaultboursier/use-timer
- Homepage: https://github.com/thibaultboursier/use-timer#readme
- Issues: https://github.com/thibaultboursier/use-timer/issues
- npm.io page: https://npm.io/package/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

- 2.0.1 (latest) — 2020-10-23
- 2.0.0 — 2020-10-23
- 1.4.0 — 2020-09-17
- 1.3.0 — 2020-05-08
- 1.2.0 — 2020-04-12
- 1.1.0 — 2020-03-22
- 1.0.8 — 2020-03-22
- 1.0.7 — 2019-12-08
- 1.0.6 — 2019-03-24
- 1.0.5 — 2019-03-24
- 1.0.4 — 2019-03-24
- 1.0.3 — 2019-03-24
- 1.0.2 — 2019-03-24
- 1.0.1 — 2019-03-24
- 1.0.0 — 2019-03-24
- … 21 more at https://npm.io/package/use-timer/versions

## README

# ⏱️ use-timer

[![npm Version](https://img.shields.io/npm/v/use-timer.svg)](https://www.npmjs.com/package/use-timer) [![License](https://img.shields.io/npm/l/use-timer.svg)](https://www.npmjs.com/package/use-timer) [![Linux Build Status](https://travis-ci.com/thibaultboursier/use-timer.svg?branch=master)](https://travis-ci.com/thibaultboursier/use-timer) [![Bundle size](https://badgen.net/bundlephobia/min/use-timer?label=size)](https://bundlephobia.com/result?p=use-timer) [![Bundle size](https://badgen.net/bundlephobia/minzip/use-timer?label=gzip%20size)](https://bundlephobia.com/result?p=use-timer)

Simple timer turned into React Hooks.
Read about [Hooks](https://reactjs.org/docs/hooks-intro.html) feature.

## Installation

```
npm i use-timer
```

With [Yarn](https://yarnpkg.com/):

```
yarn add use-timer
```

## Demo

[![Netlify Status](https://api.netlify.com/api/v1/badges/3be3466e-4bc9-46f1-89b0-9b09910cc20b/deploy-status)](https://app.netlify.com/sites/use-timer/deploys)

🚀 Try last production version on Netlify!

https://use-timer.netlify.app/

## Usage

### Basic timer

```tsx
import React from 'react';
import { useTimer } from 'use-timer';

const App = () => {
  const { time, start, pause, reset, status } = useTimer();

  return (
    <>
      <div>
        <button onClick={start}>Start</button>
        <button onClick={pause}>Pause</button>
        <button onClick={reset}>Reset</button>
      </div>
      <p>Elapsed time: {time}</p>
      {status === 'RUNNING' && <p>Running...</p>}
    </>
  );
};
```

### Decremental timer

```tsx
const { time, start, pause, reset, status } = useTimer({
  initialTime: 100,
  timerType: 'DECREMENTAL',
});
```

### Timer with end time

```tsx
const { time, start, pause, reset, status } = useTimer({
  endTime: 30,
  initialTime: 10,
});
```

### Advance time

This works for all types of timer (incremental and decremental).

```tsx
const { time, start, advanceTime } = useTimer({
  initialTime: 20,
});

start();
advanceTime(10);

console.log(time); // 30
```

## Callbacks

Some callback functions can be provided.

### When time is over

```tsx
const { time, start, pause, reset, status } = useTimer({
  endTime,
  onTimeOver: () => {
    console.log('Time is over');
  },
});
```

### When time is updated

```tsx
const { time, start, pause, reset, status } = useTimer({
  endTime,
  onTimeUpdate: (time) => {
    console.log('Time is updated', time);
  },
});
```

## Configuration

The configuration and all its parameters are optional.

| Property     | Type     | Default value | Description                                                                            |
| ------------ | -------- | ------------- | -------------------------------------------------------------------------------------- |
| autostart    | boolean  | false         | Pass true to start timer automatically                                                 |
| endTime      | number   | null          | The value for which timer stops                                                        |
| initialTime  | number   | 0             | The starting value for the timer                                                       |
| interval     | number   | 1000          | The interval in milliseconds                                                           |
| onTimeOver   | function |               | Callback function that is called when time is over                                     |
| onTimeUpdate | function |               | Callback function that is called when time is updated                                  |
| step         | number   | 1             | The value to add to each increment / decrement                                         |
| timerType    | string   | "INCREMENTAL" | The choice between a value that increases ("INCREMENTAL") or decreases ("DECREMENTAL") |

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