useInterval
Interval with start/stop.
Import
TypeScript
import { useInterval } from '@/hooks';API
Signature
useInterval(fn, delay | null, options?) → controls
When to use
Use useInterval 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 · useIntervalEditor
function Clock() { const [n, setN] = useState(0); const { isActive, stop, start } = useInterval(() => setN((x) => x + 1), 1000); return ( <div> {n} <button onClick={isActive ? stop : start}>{isActive ? 'Stop' : 'Start'}</button> </div> ); }
Preview
Implementation source
Full library source for useInterval — copy into your project when you are not installing a package yet.
hooks/timer/useInterval.ts
import { useCallback, useEffect, useRef, useState } from 'react';
import { useLatest } from '../utility/useLatest';
export interface UseIntervalControls {
isActive: boolean;
start: () => void;
stop: () => void;
toggle: () => void;
}
/**
* setInterval with start/stop and automatic cleanup.
* Pass `null` delay to disable.
*/
export function useInterval(
fn: () => void,
delay: number | null | undefined,
options: { immediate?: boolean; autoStart?: boolean } = {},
): UseIntervalControls {
const { immediate = false, autoStart = true } = options;
const fnRef = useLatest(fn);
const timerRef = useRef<ReturnType<typeof setInterval> | null>(null);
const [isActive, setIsActive] = useState(autoStart && delay !== null && delay !== undefined);
const stop = useCallback(() => {
if (timerRef.current !== null) {
clearInterval(timerRef.current);
timerRef.current = null;
}
setIsActive(false);
}, []);
const start = useCallback(() => {
stop();
if (delay === null || delay === undefined || delay < 0) return;
if (immediate) fnRef.current();
setIsActive(true);
timerRef.current = setInterval(() => {
fnRef.current();
}, delay);
}, [delay, immediate, fnRef, stop]);
const toggle = useCallback(() => {
if (isActive) stop();
else start();
}, [isActive, start, stop]);
useEffect(() => {
if (autoStart) start();
return stop;
}, [delay, autoStart]);
return { isActive, start, stop, toggle };
}
Copy-paste example
useInterval.example.tsx
'use client';
import { useState } from 'react';
import { useInterval } from '@/hooks';
export function Clock() {
const [n, setN] = useState(0);
const { isActive, stop, start } = useInterval(() => setN((x) => x + 1), 1000);
return (
<div>
{n}
<button onClick={isActive ? stop : start}>{isActive ? 'Stop' : 'Start'}</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/useInterval.tsfor implementation details