useTimer

Timing & async

A powerful, accurate countdown timer hook for React applications

Install

$ npm install @usefy/use-timer

Quick start

useTimer.tsx

import { useTimer, ms } from "@usefy/use-timer";

function Timer() {
  const timer = useTimer(ms.minutes(5), { format: "MM:SS" });

  return (
    <div>
      <p>{timer.time}</p>
      <button onClick={timer.toggle}>
        {timer.isRunning ? "Pause" : "Start"}
      </button>
      <button onClick={timer.reset}>Reset</button>
    </div>
  );
}

API reference

`useTimer(initialTimeMs, options?)`

A hook that manages countdown timer state with comprehensive controls.

Parameters

Parameter	Type	Description
`initialTimeMs`	`number`	Initial countdown time in milliseconds
`options`	`UseTimerOptions`	Optional configuration object

Options

Option	Type	Default	Description
`interval`	`number`	`1`	Update interval in ms. Coarse formats re-render at most once per second, so prefer a larger value (e.g. `250`) for them and reserve `1` for millisecond-precision formats.
`format`	`TimeFormat \| TimeFormatter`	`"MM:SS"`	Time display format or custom formatter function
`autoStart`	`boolean`	`false`	Start timer automatically on mount
`loop`	`boolean`	`false`	Restart timer automatically when it completes
`useRAF`	`boolean`	`false`	Use `requestAnimationFrame` instead of interval
`onComplete`	`() => void`	-	Callback when timer reaches 0
`onTick`	`(remaining: number) => void`	-	Callback on each tick with remaining time
`onStart`	`() => void`	-	Callback when timer starts
`onPause`	`() => void`	-	Callback when timer is paused
`onReset`	`() => void`	-	Callback when timer is reset
`onStop`	`() => void`	-	Callback when timer is stopped

Time Formats

Format	Example	Description
`"MM:SS"`	`05:30`	Minutes and seconds
`"HH:MM:SS"`	`01:05:30`	Hours, minutes, and seconds
`"SS"`	`330`	Total seconds
`"mm:ss.SSS"`	`05:30.123`	Minutes, seconds, and milliseconds
`"HH:MM:SS.SSS"`	`01:05:30.123`	Full format with milliseconds
Custom function	Any string	`(ms: number) => string`

Returns `UseTimerReturn`

Property	Type	Description
`time`	`string`	Formatted time string (e.g., "05:30")
`progress`	`number`	Progress percentage (0-100)
`status`	`TimerStatus`	Current status: `idle`, `running`, `paused`, `finished`
`isRunning`	`boolean`	Whether timer is running
`isPaused`	`boolean`	Whether timer is paused
`isFinished`	`boolean`	Whether timer has finished
`isIdle`	`boolean`	Whether timer is idle
`start`	`() => void`	Start the timer
`pause`	`() => void`	Pause the timer
`stop`	`() => void`	Stop timer (keep current time)
`reset`	`() => void`	Reset to initial time
`restart`	`() => void`	Reset and immediately start
`toggle`	`() => void`	Toggle between start/pause
`addTime`	`(ms: number) => void`	Add time to the timer
`subtractTime`	`(ms: number) => void`	Subtract time from the timer
`setTime`	`(ms: number) => void`	Set timer to a specific value

`ms` Helper Object

A utility object for converting time units to milliseconds.

import { ms } from "@usefy/use-timer";

ms.seconds(30); // 30000
ms.minutes(5); // 300000
ms.hours(1); // 3600000

// Combine them
ms.hours(1) + ms.minutes(30); // 1h 30m = 5400000

Go deeper

This page is the quick reference. For every example, prop, and edge case, read the full README — or open Storybook to change props live.

Full README →Open in Storybook →