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 · useStopwatchEditor
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.tsfor implementation details