Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/thibaultboursier/use-timer

A timer hook for React
https://github.com/thibaultboursier/use-timer

clock countdown react react-hook react-hooks time timer

Last synced: 3 months ago
JSON representation

A timer hook for React

Awesome Lists containing this project

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 (
<>


Start
Pause
Reset

Elapsed time: {time}


{status === 'RUNNING' &&

Running...

}
>
);
};
```

### 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 |
| initialStatus | string | "STOPPED" | The initial status for the timer. Options are: "RUNNING", "PAUSED", and "STOPPED" |
| 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") |