useDebouncedValue
Return a value that updates after a quiet period.
Import
TypeScript
import { useDebouncedValue } from '@/hooks';API
Signature
useDebouncedValue<T>(value, delay | options) → T
When to use
Search boxes, resize handlers, expensive derived filters.
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 · useDebouncedValueEditor
function Search() { const [q, setQ] = useState(''); const debounced = useDebouncedValue(q, 400); return <input value={q} onChange={(e) => setQ(e.target.value)} placeholder={debounced} />; }
Preview
Implementation source
Full library source for useDebouncedValue — copy into your project when you are not installing a package yet.
hooks/performance/useDebouncedValue.ts
import { useEffect, useState } from 'react';
import type { DebounceOptions } from '../types';
import { useDebouncedCallback } from './useDebouncedCallback';
/**
* Returns a debounced copy of `value`.
*/
export function useDebouncedValue<T>(
value: T,
delayOrOptions: number | DebounceOptions = 300,
): T {
const [debounced, setDebounced] = useState(value);
const update = useDebouncedCallback((next: T) => {
setDebounced(next);
}, delayOrOptions);
useEffect(() => {
update(value);
}, [value, update]);
return debounced;
}
Copy-paste example
useDebouncedValue.example.tsx
'use client';
import { useState } from 'react';
import { useDebouncedValue } from '@/hooks';
export function Search() {
const [q, setQ] = useState('');
const debounced = useDebouncedValue(q, 400);
return <input value={q} onChange={(e) => setQ(e.target.value)} placeholder={debounced} />;
}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/useDebouncedValue.tsfor implementation details