Package Exports

react-use-timer-hook
react-use-timer-hook/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (react-use-timer-hook) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

React Use Timer Hook

GitHub License

A flexible and easy-to-use React custom hook for timer functionality, supporting countdown and count-up modes, pause/resume, and detailed time tracking. Perfect for building timers, countdowns, stopwatches, and progress indicators in your React apps.

Features

Countdown & Count Up: Switch between decrementing and incrementing timer modes.
Pause/Resume: Pause the timer and track total pause duration.
Granular Time Breakdown: Get hours, minutes, seconds, and milliseconds.
Reducer-based State: Predictable state management using a reducer pattern.
Custom Callbacks: Hooks for onTick, onFinish, and onReset events.
TypeScript Support: Fully typed API for safety and autocompletion.

Installation

npm install react-use-timer-hook
# or
yarn add react-use-timer-hook
# or
pnpm add react-use-timer-hook

Usage

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

function TimerComponent() {
  const {
    hours,
    minutes,
    seconds,
    milliseconds,
    isRunning,
    isPaused,
    start,
    pause,
    reset,
    isFinished,
  } = useTimer({
    initialTime: 60, // seconds
    countUp: false,  // countdown mode
    onFinish: () => alert('Time is up!'),
    onStart: () => console.log('Started!'),
    onPause: () => console.log('Paused!'),
  });

  return (
    <div>
      <h1>{`${hours}:${minutes}:${seconds}`}</h1>
      <button onClick={start}>Start</button>
      <button onClick={pause}>Pause</button>
      <button onClick={reset}>Reset</button>
  <div>{isRunning ? 'Running' : isPaused ? 'Paused' : isFinished ? 'Finished' : 'Stopped'}</div>
    </div>
  );
}

API

`useTimer(options)`

Options

Name	Type	Default	Description
time	number	60	Initial time in seconds
countUp	boolean	false	If true, timer counts up instead of down
autoStart	boolean	false	Start timer automatically
onFinish	function	-	Callback when timer finishes
onTick	function	-	Callback on every tick
onReset	function	-	Callback when timer resets
onPause	function	-	Callback when timer is paused
onStart	function	-	Callback when timer is started

Return Values

Name	Type	Description
hours	number	Current hours
minutes	number	Current minutes
seconds	number	Current seconds
milliseconds	number	Current milliseconds
totalSeconds	number	Total seconds remaining or elapsed
totalMilliseconds	number	Total milliseconds remaining or elapsed
isRunning	boolean	Timer is running
isPaused	boolean	Timer is paused
isFinished	boolean	Timer has finished
pauseTime	object	Current pause session duration
totalPauseTime	object	Total pause time
start	function	Start or resume the timer
pause	function	Pause the timer
reset	function	Reset the timer to initial state
setTime	function	Set the timer to a specific time (seconds)

Advanced Usage

Count Up Mode: Set countUp: true.
Custom Time Display: Use hours, minutes, seconds, or totalSeconds for progress bars.
Pause Tracking: Access pauseTime and totalPauseTime for analytics or UI.
Detect Finished State: Use isFinished to know when the timer has completed.
Lifecycle Callbacks: Use onStart and onPause for custom logic when timer starts or pauses.

Example

const timer = useTimer({
  time: 20,
  countUp: true,
  autoStart: true,
  onFinish: () => console.log('Done!'),
});

Development

Built with React hooks and TypeScript
Uses dayjs for time calculations
Reducer pattern for state management

License

This project is licensed under the MIT License. See the LICENSE file for details.