https://github.com/yassinedoghri/react-timer-machine
React Timer Machine is a fully controllable and customizable timer component for react
https://github.com/yassinedoghri/react-timer-machine
countdown react react-component-library stopwatch timer
Last synced: 5 months ago
JSON representation
React Timer Machine is a fully controllable and customizable timer component for react
- Host: GitHub
- URL: https://github.com/yassinedoghri/react-timer-machine
- Owner: yassinedoghri
- License: mit
- Created: 2018-06-02T10:49:18.000Z (over 7 years ago)
- Default Branch: main
- Last Pushed: 2022-07-10T09:38:02.000Z (over 3 years ago)
- Last Synced: 2025-04-24T19:01:54.365Z (6 months ago)
- Topics: countdown, react, react-component-library, stopwatch, timer
- Language: JavaScript
- Homepage: https://react-timer-machine.yassinedoghri.com
- Size: 1.83 MB
- Stars: 12
- Watchers: 1
- Forks: 2
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
⌛ react-timer-machine
**React Timer Machine is a fully controllable and customizable timer component for react**
[![npm-badge]][npm] [![deploy-badge]][deploy] [![test-suite-badge]][test-suite] [![maintainability-badge]][maintainability] [![test-coverage-badge]][test-coverage] [![license-badge]][license] [![stars-badge]][stars]
## Install
```bash
npm install --save react-timer-machine
```
or
```bash
yarn add react-timer-machine
```
## Usage
```jsx
import React, { Component } from "react";
import TimerMachine from "react-timer-machine";
import moment from "moment";
import momentDurationFormatSetup from "moment-duration-format";
momentDurationFormatSetup(moment);
class Example extends Component {
render() {
return (
moment.duration(ms, "milliseconds").format("h:mm:ss")
}
onStart={(time) =>
console.info(`Timer started: ${JSON.stringify(time)}`)
}
onStop={(time) =>
console.info(`Timer stopped: ${JSON.stringify(time)}`)
}
onTick={(time) => console.info(`Timer ticked: ${JSON.stringify(time)}`)}
onPause={(time) =>
console.info(`Timer paused: ${JSON.stringify(time)}`)
}
onResume={(time) =>
console.info(`Timer resumed: ${JSON.stringify(time)}`)
}
onComplete={(time) =>
console.info(`Timer completed: ${JSON.stringify(time)}`)
}
/>
);
}
}
```
## User guide
### TimerMachine
Renders a [React Fragment](https://reactjs.org/docs/fragments.html) to be fully customized.
You can easily style the timer states thanks to the provided function callbacks.
By default, TimerMachine displays the time formatted as: `hh:mm:ss.SSS`.
The format can be changed using the `formatTimer` property. [See usage example](#usage) above.
### Props
| Name | Type | Default | Description |
| -------------------- | ---------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| timeStart `required` | `number` | - | The initial time on which the timer is set (in ms) |
| timeEnd | `number` | `0` | The time on which the timer will complete (in ms) |
| countdown | `boolean` | `false` | When `true`, sets the timer to countdown instead of counting up |
| interval | `number` | `1000` | The time between each ticks (in ms) |
| started | `boolean` | `false` | Starts the timer when set to `true`, stops it when set to `false` |
| paused | `boolean` | `false` | Pauses the timer when set to `true`, resumes it when set to `false` |
| formatTimer | `function` | `(timer: Timer, ms: number) => 'hh:mm:ss.SSS'` | Function to format the timer before it renders. You can use [moment-duration] as shown above or write your own |
| onStart | `function` | `(timer: Timer) => void` | Callback function called on timer start |
| onTick | `function` | `(timer: Timer) => void` | Callback function called on each timer tick |
| onPause | `function` | `(timer: Timer) => void` | Callback function called on timer pause |
| onResume | `function` | `(timer: Timer) => void` | Callback function called when timer resumes |
| onStop | `function` | `(timer: Timer) => void` | Callback function called on timer stop |
| onComplete | `function` | `(timer: Timer) => void` | Callback function called on timer complete |
[moment-duration]: https://github.com/jsmreese/moment-duration-format
### Types
| Name | Example values |
| -------------- | ------------------------------- |
| Timer `object` | `{ h: 1, m: 30, s: 30, ms: 0 }` |
## Versioning
react-timer-machine is maintained under [the Semantic Versioning guidelines](http://semver.org/).
## Contributing
Love react-timer-machine and would like to help? Check out the [contribution guidelines for this project](./CONTRIBUTING.md), everything should be there!
## Contributors
**Yassine Doghri** _(creator)_
- [https://yassinedoghri.com](https://yassinedoghri.com)
- [https://twitter.com/yassinedoghri](https://twitter.com/yassinedoghri)
- [https://github.com/yassinedoghri](https://github.com/yassinedoghri)
## Copyright and licence
Code and documentation copyright 2018, [Yassine Doghri](https://github.com/yassinedoghri). Code released under the MIT License.
[npm]: https://www.npmjs.com/package/react-timer-machine
[npm-badge]: https://img.shields.io/npm/v/react-timer-machine.svg
[deploy]: https://github.com/yassinedoghri/react-timer-machine/actions/workflows/deploy.yml
[deploy-badge]: https://img.shields.io/github/workflow/status/yassinedoghri/react-timer-machine/react-timer-machine-deploy-example/main?label=deploy
[test-suite]: https://github.com/yassinedoghri/react-timer-machine/actions/workflows/test.yml
[test-suite-badge]: https://img.shields.io/github/workflow/status/yassinedoghri/react-timer-machine/react-timer-machine-test-suite/main?label=test%20suite
[maintainability]: https://codeclimate.com/github/yassinedoghri/react-timer-machine/maintainability
[maintainability-badge]: https://api.codeclimate.com/v1/badges/67abb76788a89f4805fc/maintainability
[test-coverage]: https://codeclimate.com/github/yassinedoghri/react-timer-machine/test_coverage
[test-coverage-badge]: https://api.codeclimate.com/v1/badges/67abb76788a89f4805fc/test_coverage
[license]: https://opensource.org/licenses/MIT
[license-badge]: https://img.shields.io/badge/License-MIT-blue.svg
[stars]: https://github.com/yassinedoghri/react-timer-machine/stargazers
[stars-badge]: https://img.shields.io/github/stars/yassinedoghri/react-timer-machine?style=social