TimerBeginnerSSR-safehooks/timer/useTimeoutFn.ts

useTimeoutFn

Imperative start/clear timeout.

Import

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

API

Signature

useTimeoutFn(fn, delay) → { start, clear, reset, isPending }

When to use

Use useTimeoutFn 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 · useTimeoutFn
Editor
function Delayed() {
  const { start, clear, isPending } = useTimeoutFn(() => alert('done'), 1000);
  return (
    <>
      <button onClick={start}>Start</button>
      <button onClick={clear}>Cancel</button>
      <span>{isPending ? '…' : 'idle'}</span>
    </>
  );
}
Preview

Implementation source

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

hooks/timer/useTimeoutFn.ts
import { useCallback, useEffect, useRef, useState } from 'react';
import { useLatest } from '../utility/useLatest';

export interface UseTimeoutFnReturn {
  /** Whether a timer is currently scheduled. */
  isPending: boolean;
  /** (Re)start the timer. */
  start: () => void;
  /** Cancel the timer. */
  clear: () => void;
  /** Alias for start. */
  reset: () => void;
}

/**
 * Declarative setTimeout with start/clear controls.
 * Timer is cleaned up on unmount and when delay changes.
 */
export function useTimeoutFn(
  fn: () => void,
  delay: number | null | undefined,
): UseTimeoutFnReturn {
  const fnRef = useLatest(fn);
  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
  const [isPending, setIsPending] = useState(false);

  const clear = useCallback(() => {
    if (timerRef.current !== null) {
      clearTimeout(timerRef.current);
      timerRef.current = null;
    }
    setIsPending(false);
  }, []);

  const start = useCallback(() => {
    clear();
    if (delay === null || delay === undefined || delay < 0) return;
    setIsPending(true);
    timerRef.current = setTimeout(() => {
      timerRef.current = null;
      setIsPending(false);
      fnRef.current();
    }, delay);
  }, [clear, delay, fnRef]);

  useEffect(() => {
    return clear;
  }, [clear, delay]);

  return { isPending, start, clear, reset: start };
}

Copy-paste example

useTimeoutFn.example.tsx
'use client';

import { useTimeoutFn } from '@/hooks';

export function Delayed() {
  const { start, clear, isPending } = useTimeoutFn(() => alert('done'), 1000);
  return (
    <>
      <button onClick={start}>Start</button>
      <button onClick={clear}>Cancel</button>
      <span>{isPending ? '…' : 'idle'}</span>
    </>
  );
}

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/useTimeoutFn.ts for implementation details