react-hook-time

react-hook-time is a library for React that allows you to create timers and stopwatches in your applications. It supports TypeScript and provides a simple and clear API, making it easy to customize according to your needs. You can set initial time, choose time units, configure callbacks, and much more.

Open basic demo to see how it works

Go to npm page

Install

npm install react-hook-time

Quickstart

import useTimer from 'react-hook-time'

function App() {
  const { currentTime, start, pause, reset } = useTimer(10, {
    onEnd: () => console.log('Timer ended'),
  })

  return (
    <div>
      <div>Current time {currentTime}</div>
      <button onClick={start}>start</button>
      <button onClick={pause}>pause</button>
      <button onClick={() => {
        // chaining functions
        reset().pause()
      }}>
        reset
      </button>
    </div>
  )
}

API

There are few options to initialize timer. You can pass:

• initialTime
• initialTime and settings object
• settings object
• leave it empty to set it up later with setTime for async setup

initialTime can be number or Date object

const timer = useTimer(10)
const timerFromDate = useTimer(new Date('2023-12-01'))
const timerWithoutUpdates = useTimer(15, { stopUpdate: true })
const stopwatch = useTimer({ stopwatch: true })
const timerWithoutSettings = useTimer()

Props

name	description	type	default value
autostart	enables autostart on component mount	boolean	false
step*	by default tick step is 1000 millisecond (1 sec). But you can change it	number	1000
timeUnit	indicates the default time unit in which the timer will operate	'ms' | 'sec' | 'min' | 'hour' | 'day'	'sec'
stopUpdate*	disables component re-render on every tick	boolean	false
stopwatch*	enables stopwatch with time going up	boolean	false
speedUpFirstSecond*	first tick will happen faster after timer starts. Visual thing similar to iOS timers	boolean	false

speedUpFirstSecond - сompare the two sides. In both cases, the 'start' button was clicked simultaneously. However, on the right side, the timer visually starts faster.

step

stopUpdate - with this prop most of the callbacks are not working. Only onStart, onEnd and onCancel are available. currentTime and formattedCurrentTime is not available. Use getCurrentTime() and getFormattedCurrentTime() instead.

stopwatch - with this prop onEnd callback is disabled

Methods

const timer = useTimer(10)

timer returns some values and functions. You can use them separately timer.start() or chain them if required timer.reset().pause()

name	description	type
currentTime	current time	number
getCurrentTime	same as currentTime but for stopUpdate=true	number
formattedCurrentTime	you can get years, days, hours, minutes, seconds from this object	object
getFormattedCurrentTime	same as formattedCurrentTime but for stopUpdate=true	object
isRunning	current timer state	boolean
start	start timer	() => void
pause	pause timer	() => void
reset	reset time to initial value	() => void
setStep	set new step in milliseconds	(number) => void
setTime	set new time value	(timeAmount, timeSettings) => void
decTime	decrease time	(timeAmount, timeSettings) => void
incTime	increase time	(timeAmount, timeSettings) => void

timeAmount

timeAmount can be number or Date object

timeSettings

name	description	type	default value
timeUnit	specifying the time unit to perform a function	'ms' | 'sec' | 'min' | 'hour' | 'day'	'sec' or timeUnit used in useTimer props

Callbacks

name	description	return value
onCancel	triggers when timer was cancelled	undefined
onEnd	triggers when timer was ended	undefined
onPause	triggers when timer was paused	currentTime
onStart	triggers when timer was started	currentTime
onReset	triggers when timer was reseted	currentTime
onUpdate	triggers on every tick	currentTime
onTimeSet	triggers when timer was set	currentTime
onTimeInc	triggers when timer was increased	currentTime
onTimeDec	triggers when timer was decreased	currentTime
onStepSet	triggers when step was set	step