TimerBeginnerSSR-safehooks/timer/useStopwatch.ts

useStopwatch

Elapsed time stopwatch.

Import

TypeScript
import { useStopwatch } from '@/hooks';

API

Signature

useStopwatch(options?) → stopwatch controls

When to use

Use useStopwatch instead of re-implementing the same pattern in multiple components.

SSR / Next.js

Timers start in effects — no server timers.

Live playground

Edit the example and see it run against the real @/hooks package in this app.

Live playgroundEdit · run with real @/hooks · useStopwatch
Editor
function Timer() {
  const { seconds, isRunning, start, pause, reset } = useStopwatch();
  return (
    <div>
      <p>{seconds.toFixed(1)}s</p>
      <button onClick={isRunning ? pause : start}>{isRunning ? 'Pause' : 'Start'}</button>
      <button onClick={reset}>Reset</button>
    </div>
  );
}
Preview

Implementation source

Full library source for useStopwatch — copy into your project when you are not installing a package yet.

hooks/timer/useStopwatch.ts
import { useCallback, useRef, useState } from 'react';
import { useInterval } from './useInterval';

export interface UseStopwatchReturn {
  /** Elapsed milliseconds. */
  ms: number;
  seconds: number;
  isRunning: boolean;
  start: () => void;
  stop: () => void;
  pause: () => void;
  resume: () => void;
  reset: () => void;
}

/** Stopwatch with start/pause/reset. */
export function useStopwatch(
  options: { intervalMs?: number; autoStart?: boolean } = {},
): UseStopwatchReturn {
  const { intervalMs = 100, autoStart = false } = options;
  const [ms, setMs] = useState(0);
  const [isRunning, setIsRunning] = useState(autoStart);
  const startedAt = useRef<number | null>(null);
  const baseMs = useRef(0);

  const tick = useCallback(() => {
    if (startedAt.current === null) return;
    setMs(baseMs.current + (Date.now() - startedAt.current));
  }, []);

  useInterval(tick, isRunning ? intervalMs : null);

  const start = useCallback(() => {
    if (isRunning) return;
    startedAt.current = Date.now();
    setIsRunning(true);
  }, [isRunning]);

  const stop = useCallback(() => {
    if (startedAt.current !== null) {
      baseMs.current += Date.now() - startedAt.current;
      startedAt.current = null;
    }
    setIsRunning(false);
    setMs(baseMs.current);
  }, []);

  const reset = useCallback(() => {
    startedAt.current = null;
    baseMs.current = 0;
    setMs(0);
    setIsRunning(false);
  }, []);

  return {
    ms,
    seconds: ms / 1000,
    isRunning,
    start,
    stop,
    pause: stop,
    resume: start,
    reset,
  };
}

Copy-paste example

useStopwatch.example.tsx
'use client';

import { useStopwatch } from '@/hooks';

export function Timer() {
  const { seconds, isRunning, start, pause, reset } = useStopwatch();
  return (
    <div>
      <p>{seconds.toFixed(1)}s</p>
      <button onClick={isRunning ? pause : start}>{isRunning ? 'Pause' : 'Start'}</button>
      <button onClick={reset}>Reset</button>
    </div>
  );
}

Production checklist

  • Called only from Client Components or other custom hooks
  • Type parameters filled in (e.g. useFetch<User[]>)
  • Tip: Pass null delay to pause/disable intervals and timeouts without unmounting.
  • Source of truth: open hooks/timer/useStopwatch.ts for implementation details