|
| 1 | +# react-timer-wrapper |
| 2 | + |
| 3 | +Composable React Timer component that passes status props to children, in addition |
| 4 | +to some basic callbacks. Can be used at a countdown timer ⏲ or as stopwatch ⏱ to track |
| 5 | +time while active. |
| 6 | + |
| 7 | +## Install |
| 8 | + |
| 9 | +Via [npm](https://npmjs.com/package/react-timer-wrapper): |
| 10 | +``` |
| 11 | +npm install --save react-timer-wrapper |
| 12 | +``` |
| 13 | + |
| 14 | +Via [Yarn](https://yarn.fyi/react-timer-wrapper): |
| 15 | +``` |
| 16 | +yarn add react-timer-wrapper |
| 17 | +``` |
| 18 | + |
| 19 | +## How to use |
| 20 | + |
| 21 | +The `Timer` can be used in a couple different ways. You could use it as a standalone |
| 22 | +timer and setup callbacks to trigger things to happen in your project. Or, wrap |
| 23 | +child components in `Timer` component, where those children will receive |
| 24 | +props passed in by the `Timer`. |
| 25 | + |
| 26 | +It can be used as a countdown timer, which will fire the `onFinish` event upon |
| 27 | +completion. Or, you can use it to track the time that occurs while it’s active. |
| 28 | + |
| 29 | +### Properties |
| 30 | + |
| 31 | +* `active:Boolean` - Start/stop the timer. (Default: `false`) |
| 32 | +* `duration:Number` - Enables countdown mode and is the number of milliseconds to count before firing `onFinish`. (Default: `10000`) |
| 33 | +* `loop:Boolean` - Enable looping of the countdown timer. (Default: `false`) |
| 34 | +* `time:Number` - Either used as a time offset for the duration when used as a countdown timer, or the initial time to start from when used for tracking time. (Default: `0`) |
| 35 | +* `onFinish:Function` - Callback fired when the timer has finished. (Fired in countdown mode only) |
| 36 | +* `onStart:Function` - Callback fired when the timer is started. |
| 37 | +* `onStop:Function` - Callback fired when the timer is stopped. |
| 38 | +* `onTimeUpdate:Function` - Callback fired when time updates. |
| 39 | + |
| 40 | +### Examples |
| 41 | + |
| 42 | +#### Standalone |
| 43 | + |
| 44 | +``` |
| 45 | +import Timer from 'react-timer-wrapper'; |
| 46 | +
|
| 47 | +... |
| 48 | +
|
| 49 | + onTimerStart({duration, progress, time}) { |
| 50 | +
|
| 51 | + } |
| 52 | +
|
| 53 | + onTimerStop({duration, progress, time}) { |
| 54 | +
|
| 55 | + } |
| 56 | +
|
| 57 | + onTimerTimeUpdate({duration, progress, time}) { |
| 58 | +
|
| 59 | + } |
| 60 | +
|
| 61 | + onTimerFinish({duration, progress, time}) { |
| 62 | +
|
| 63 | + } |
| 64 | +
|
| 65 | + render() { |
| 66 | + const { |
| 67 | + timerActive, |
| 68 | + } = this.state; |
| 69 | +
|
| 70 | + return ( |
| 71 | + <Timer |
| 72 | + active={timerActive} |
| 73 | + onFinish={this.onTimerFinish} |
| 74 | + onStart={this.onTimerStart} |
| 75 | + onStop={this.onTimerStop} |
| 76 | + onTimeUpdate={this.onTimerTimeUpdate} |
| 77 | + /> |
| 78 | + ); |
| 79 | + } |
| 80 | +
|
| 81 | +... |
| 82 | +
|
| 83 | +``` |
| 84 | + |
| 85 | +#### With children |
| 86 | + |
| 87 | +``` |
| 88 | +import Timer from 'react-timer-wrapper'; |
| 89 | +import CircleIndicator from 'react-indicators'; |
| 90 | +
|
| 91 | +... |
| 92 | +
|
| 93 | + render() { |
| 94 | + const { |
| 95 | + timerShouldRun, |
| 96 | + } = this.state; |
| 97 | +
|
| 98 | + return ( |
| 99 | + <Timer active={timerShouldRun}> |
| 100 | + <CircleIndicator /> |
| 101 | + </Timer> |
| 102 | + ); |
| 103 | + } |
| 104 | +
|
| 105 | +... |
| 106 | +
|
| 107 | +``` |
| 108 | + |
| 109 | +### Children |
| 110 | + |
| 111 | +The `Timer` allows you to easily compose components that provide a visual |
| 112 | +status of the timer. Each children receives the following props that you can use |
| 113 | +to communicate the status of the timer. |
| 114 | + |
| 115 | +* `duration:Number` - Duration of the countdown timer. _(Available for countdown timers only, `null` passed when used for time tracking)_ |
| 116 | +* `progress:Number` - Current percentage of timer complete. _(Available for countdown timers only, `null` passed when used for time tracking)_ |
| 117 | +* `time:Number` - Current time on the timer in milliseconds. |
| 118 | + |
| 119 | +## Pairs well with... |
| 120 | + |
| 121 | +* [react-indicators](https://github.com/ryanhefner/react-indicators) |
| 122 | +* [react-timecode](https://github.com/ryanhefner/react-timecode) |
| 123 | + |
| 124 | +## License |
| 125 | + |
| 126 | +[MIT](LICENSE) |
0 commit comments