useElapsedTime React hook
React hook to measure elapsed time using requestAnimationFrame. The time measurement can be played and paused, additionally the start time and duration can be set. The primary use case of the hooks is in animations where the most important part of the animation is time.
- Toggle play/pause
- Set start time and duration
- Easily repeat the measurement
- Combine with any easing function to get the right animation
- Built-in and ready-to-use TypeScript type definitions.
Installation
yarn add use-elapsed-time
Migrating from v1.x.x to v2.x.x?
There are a few breaking changes to consider before switching to v2.x.x. Read Migrate to v2.x.x docs for more info.
Basic usage
import { useElapsedTime } from 'use-elapsed-time'
const MyComponent = () => {
const isPlaying = true
const { elapsedTime } = useElapsedTime(isPlaying)
return elapsedTime
}
Function signature
function useElapsedTime(
isPlaying: boolean,
options?: {
duration?: number,
startAt?: number,
autoResetKey?: string | number,
onComplete?: (totalElapsedTime: number) => void | { shouldRepeat: boolean, delay: number, newStartAt: number }
}
): {
elapsedTime: number,
reset?: (newStartAt: number) => void
}
1st arg. isPlaying: boolean
Default:
isPlaying = false
Indicates if the loop to get the elapsed time is running or it is paused.
2nd arg. options: object
Default:
options = {}
| Prop Name | Type | Default | Description |
|---|---|---|---|
| duration | number | - | Animation duration in seconds |
| startAt | number | 0 | Shift the start time to a different value than 0 |
| autoResetKey | string | number | - | Auto reset animation when the key changes. It works similar to React's key prop |
| onComplete | (totalElapsedTime: number) => void | { shouldRepeat: boolean, delay: number, newStartAt: number } | - | onComplete callback will be fired when the duration is reached. The callback will receive as an argument the totalElapsedTime in seconds. onComplete can be used to restart the elapsed time loop by returning an object with the following params: shouldRepeat indicates if the loop should start over; delay - delay before looping again in seconds; newStartAt set new start at value. |
Return value { elapsedTime, reset }
The hook returns an object with elapsedTime in seconds and reset method.
Use cases
Countdown timer
Count up animation
Non-liner path animation
