useDebouncedValue
Returns a debounced copy of a value that only updates once the value has
stopped changing for a given delay. It is the debounce counterpart to
useThrottledValue: debouncing waits for a
pause, throttling guarantees regular updates while the value keeps changing.
To debounce a function call instead, use
useDebouncedCallback.
When to use it
- Running a search or fetch only once the user stops typing.
- Validating a field after the user pauses, instead of on every keystroke.
- Deferring expensive filtering or rendering driven by fast-changing input.
Demo
Type in the field and compare the live and debounced values. Open the Console tab to see when the search effect runs.
Loading demo…
Signature
function useDebouncedValue<T>(value: T, delay: number): T;
| Parameter | Type | Description |
|---|---|---|
value | T | The value to debounce. |
delay | number | How long value must stay unchanged, in milliseconds. |
Returns: the debounced value. On the first render it equals value.
Usage notes
- Every change restarts the wait, so while the value keeps changing faster
than
delay, the returned value stays the same. - Values are compared with
Object.is. Pass a stable reference (for example memoized objects) to avoid treating equal content as a change. - Changing
delayrestarts the current wait with the new delay. - Function values are stored as-is, never called.
- The pending update is dropped on unmount, and the hook is safe under
React
StrictMode.
Example
const [query, setQuery] = useState("");
const debouncedQuery = useDebouncedValue(query, 300);
const { data } = useApi<Result[]>(
`/api/search?q=${encodeURIComponent(debouncedQuery)}`
);
Hook source
View useDebouncedValue source
useDebouncedValue sourceuse-debounced-value.ts
import { useEffect, useState } from "react";
/**
* Returns a debounced copy of `value` that only updates once `value` has
* stopped changing for `delay` milliseconds.
*
* Every change restarts the wait, so while `value` keeps changing faster than
* `delay` the returned value stays the same. On the first render it equals
* `value`. It is the debounce counterpart to `useThrottledValue`, which instead
* guarantees regular updates while the value keeps changing. To debounce a
* function call rather than a value, use `useDebouncedCallback`.
*
* Values are compared with `Object.is`, a changed `delay` restarts the current
* wait, and the pending update is dropped on unmount.
*
* @typeParam T - The type of the value to debounce.
* @param value - The value to debounce.
* @param delay - How long `value` must stay unchanged, in milliseconds.
* @returns The debounced value.
*
* @example
* ```tsx
* const [query, setQuery] = useState("");
* const debouncedQuery = useDebouncedValue(query, 300);
*
* // Only fetches once the user pauses typing for 300 ms.
* const { data } = useApi(`/api/search?q=${encodeURIComponent(debouncedQuery)}`);
*
* return <input value={query} onChange={(e) => setQuery(e.target.value)} />;
* ```
*
* For a live, editable example, see the [useDebouncedValue docs page](https://altalyst-solutions.github.io/hookify/hooks/use-debounced-value).
*/
export const useDebouncedValue = <T>(value: T, delay: number): T => {
const [debounced, setDebounced] = useState(value);
useEffect(() => {
const timer = setTimeout(() => setDebounced(() => value), delay);
return () => clearTimeout(timer);
}, [value, delay]);
return debounced;
};