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