TimerBeginnerSSR-safehooks/timer/useInterval.ts

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 · useInterval
Editor
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.ts for implementation details