Skip to content

React Timer Machine is a fully controllable and customizable timer component for react

License

Notifications You must be signed in to change notification settings

yassinedoghri/react-timer-machine

Repository files navigation

⌛ react-timer-machine

React Timer Machine is a fully controllable and customizable timer component for react

npm-badge deploy-badge test-suite-badge maintainability-badge test-coverage-badge license-badge stars-badge

Install

npm install --save react-timer-machine

or

yarn add react-timer-machine

Usage

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 (
      <TimerMachine
        timeStart={10 * 1000} // start at 10 seconds
        timeEnd={20 * 1000} // end at 20 seconds
        started={true}
        paused={false}
        countdown={false} // use as stopwatch
        interval={1000} // tick every 1 second
        formatTimer={(time, ms) =>
          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 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 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

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.

Contributing

Love react-timer-machine and would like to help? Check out the contribution guidelines for this project, everything should be there!

Contributors

Yassine Doghri (creator)

Copyright and licence

Code and documentation copyright 2018, Yassine Doghri. Code released under the MIT License.