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