PerformanceIntermediateSSR-safehooks/performance/useDebouncedValue.ts

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 · useDebouncedValue
Editor
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.ts for implementation details