PerformanceIntermediateSSR-safehooks/performance/useDebounce.ts

useDebounce

Debounce a changing value (alias of useDebouncedValue).

Import

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

API

Signature

useDebounce<T>(value, delay | options) → T

When to use

Use useDebounce instead of re-implementing the same pattern in multiple components.

SSR / Next.js

SSR-safe. Timers and rAF only run after mount / interactions.

Live playground

Edit the example and see it run against the real @/hooks package in this app.

Live playgroundEdit · run with real @/hooks · useDebounce
Editor
function Search() {
  const [q, setQ] = useState('');
  const debounced = useDebounce(q, 300);
  return (
    <>
      <input value={q} onChange={(e) => setQ(e.target.value)} />
      <p>Query API with: {debounced}</p>
    </>
  );
}
Preview

Implementation source

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

hooks/performance/useDebounce.ts
import { useDebouncedValue } from './useDebouncedValue';
import { useDebouncedCallback } from './useDebouncedCallback';
import type { DebounceOptions } from '../types';

/**
 * Dual-purpose debounce helper:
 * - value mode: `useDebounce(value, delay)`
 * - callback mode: use `useDebouncedCallback` directly
 *
 * Prefer `useDebouncedValue` / `useDebouncedCallback` for clarity.
 */
export function useDebounce<T>(
  value: T,
  delayOrOptions?: number | DebounceOptions,
): T {
  return useDebouncedValue(value, delayOrOptions);
}

export { useDebouncedValue, useDebouncedCallback };

Copy-paste example

useDebounce.example.tsx
'use client';

import { useState } from 'react';
import { useDebounce } from '@/hooks';

export function Search() {
  const [q, setQ] = useState('');
  const debounced = useDebounce(q, 300);
  return (
    <>
      <input value={q} onChange={(e) => setQ(e.target.value)} />
      <p>Query API with: {debounced}</p>
    </>
  );
}

Production checklist

  • Called only from Client Components or other custom hooks
  • Type parameters filled in (e.g. useFetch<User[]>)
  • Tip: Stable callbacks prevent child re-renders. Always cancel debounce on unmount (handled for you).
  • Source of truth: open hooks/performance/useDebounce.ts for implementation details