Registry / react-timer-hook

react-timer-hook

library4.0.5jsnpmunverified

react-timer-hook is a robust custom React hook library designed to simplify the implementation of timers, stopwatches, and general time-based logic within React components. It provides three core hooks: `useTimer` for countdowns, `useStopwatch` for count-up timers, and `useTime` for retrieving the current time. Currently stable at version `4.0.5`, the library maintains an active release cadence, frequently addressing bug fixes, dependency updates, and minor feature enhancements. A key differentiator is its out-of-the-box TypeScript support and its intelligent handling of browser tab inactivity to ensure accurate timer behavior, especially for stopwatches. It exposes a comprehensive set of time values including days, hours, minutes, seconds, milliseconds, and total raw seconds/milliseconds, along with functions for starting, pausing, resuming, and restarting timers, offering fine-grained control for various time-sensitive UI/UX requirements.

npm install react-timer-hook

github ↗package ↗

INSTALL

IMPORT

SIG · REACT-TIMER-HOOK

react-timer-hook

javascriptv4.0.5

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

useTimer

✓ import { useTimer } from 'react-timer-hook';

✗ import useTimer from 'react-timer-hook';

The `useTimer` hook is a named export. Using a default import will lead to a runtime error or a TypeScript compilation error.

useStopwatch

✓ import { useStopwatch } from 'react-timer-hook';

✗ const { useStopwatch } = require('react-timer-hook');

While some bundlers might transpile CommonJS `require` to work with ES Modules, `react-timer-hook` is primarily designed for modern ES Module `import` syntax. For TypeScript users, `import` is required.

useTime

✓ import { useTime } from 'react-timer-hook';

✗ import { UseTime } from 'react-timer-hook';

React hooks conventionally start with `use` and follow camelCase naming. Ensure correct casing when importing.

TimerControls

✓ import type { TimerControls } from 'react-timer-hook';

For TypeScript projects, `TimerControls` is an interface describing the return values and control functions of `useTimer`. It should be imported as a type using `import type`.

This quickstart demonstrates a countdown timer using `useTimer`, showcasing its display of days, hours, minutes, seconds, and milliseconds, along with controls for starting, pausing, resuming, and restarting the timer. It also includes an `onExpire` callback.

import React from 'react'; import { useTimer } from 'react-timer-hook'; interface MyTimerProps { expiryTimestamp: Date; } function MyTimer({ expiryTimestamp }: MyTimerProps) { const { totalSeconds, milliseconds, seconds, minutes, hours, days, isRunning, start, pause, resume, restart, } = useTimer({ expiryTimestamp, onExpire: () => console.warn('onExpire called'), interval: 20 }); return ( <div style={{textAlign: 'center'}}> <h1>react-timer-hook </h1> <p>Timer Demo</p> <div style={{fontSize: '100px'}}> <span>{days}</span>:<span>{hours}</span>:<span>{minutes}</span>:<span>{seconds}</span>:<span>{milliseconds}</span> </div> <p>{isRunning ? 'Running' : 'Not running'}</p> <button onClick={start}>Start</button> <button onClick={pause}>Pause</button> <button onClick={resume}>Resume</button> <button onClick={() => { const time = new Date(); time.setSeconds(time.getSeconds() + 300); // Set for 5 minutes from now restart(time); }}>Restart 5min</button> </div> ); } export default function App() { const time = new Date(); time.setSeconds(time.getSeconds() + 600); // 10 minutes timer return ( <div> <MyTimer expiryTimestamp={time} /> </div> ); }

Debug

Known issues

breakingVersion 4.0.0 introduced support for milliseconds in the `useTimer` and `useStopwatch` hooks. While not strictly a breaking API change for existing users, applications relying solely on `seconds` as the smallest unit might need to adjust their display logic or `interval` setting if they intend to leverage or avoid millisecond precision.

fix

Review timer display logic for the new `milliseconds` output. If higher precision is required, set the `interval` option to a smaller value (e.g., 20ms or 100ms) when initializing the hook.

affects: >=4.0.0

gotchaPrior to v4.0.2, TypeScript definition files were not consistently included in the distributed package. This caused compilation errors for TypeScript users attempting to import and use the library's hooks and types.

fix

Upgrade to `react-timer-hook@4.0.2` or a later version to ensure all type definitions are correctly bundled and available for TypeScript projects.

affects: <4.0.2

gotchaOlder versions of `useStopwatch` (prior to v3.0.4) experienced inaccuracies in timing when the browser tab was inactive. This was due to browser throttling of `setTimeout` and `setInterval` in background tabs, leading to incorrect stopwatch readings upon returning to the tab.

fix

Update `react-timer-hook` to version `3.0.4` or later. This version includes a critical fix that improves the accuracy of `useStopwatch` even when the browser tab is not active.

affects: <3.0.4

gotchaThe `expiryTimestamp` prop for `useTimer` is mandatory and must be a valid `Date` object representing a future point in time. Providing an invalid or `undefined` value will cause the timer to behave unexpectedly or throw runtime errors.

fix

Always ensure that `expiryTimestamp` is initialized with a valid `Date` object, such as `new Date(Date.now() + 60 * 1000)` for a timer set one minute in the future.

affects: all

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'setSeconds') at MyTimer

This error typically occurs when the `expiryTimestamp` prop passed to `useTimer` is `undefined` or not a valid `Date` object, leading to failed attempts to call Date methods.

fix

Ensure `expiryTimestamp` is always a valid `Date` object initialized with a future time, e.g., `new Date(Date.now() + 5 * 60 * 1000)` for a 5-minute timer.

Property 'useTimer' does not exist on type 'typeof import("react-timer-hook")'.

This TypeScript error indicates that type definitions are not being recognized, or you're attempting to use a default import instead of a named import for `useTimer`.

fix

Verify that you are using named imports (`import { useTimer } from 'react-timer-hook';`). If the issue persists, ensure `react-timer-hook@4.0.2` or newer is installed and your `tsconfig.json` correctly includes `node_modules/@types`.

Timer is not accurate or stops when browser tab is inactive.

This was a known bug in `react-timer-hook` versions older than `3.0.4`, especially for `useStopwatch`, where browser throttling of background tabs affected timer precision.

fix

Upgrade your `react-timer-hook` package to version `3.0.4` or higher. This version contains the necessary fix for improved accuracy in inactive browser tabs.

SyntaxError: Named export 'useTimer' not found. The requested module 'react-timer-hook' does not provide an export named 'useTimer'

This error usually arises from attempting to `require` an ES Module named export in a CommonJS environment, or incorrect module resolution setup in your build pipeline.

fix

Adopt the ES Module import syntax: `import { useTimer } from 'react-timer-hook';`. If you are strictly in a CommonJS environment, confirm your transpilation setup (e.g., Babel, Webpack) is correctly configured for ES module interop.

Upgrade

Version history

4.0.5latest on npm

Audit

Dependencies

reactrequiredRuntime dependency for all React hooks, specifically requires React >=16.8.0 for Hooks API.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/amrlabib/react-timer-hook ↗

packagehttps://www.npmjs.com/package/react-timer-hook ↗