useDebouncedValue

useDebouncedValue is a React hook that returns a debounced copy of the given value. The caller keeps owning the state; the hook only delays how quickly the returned value follows it. The returned value updates wait milliseconds after the last change, which is useful for deriving a search query or a validation input from fast-changing state.

Pending updates are cancelled when the component unmounts. The example displays the delayed query without requiring a search service or an additional component.

On the first render and on the server the value is returned as is. A change is never scheduled on mount, so with leading: true the first change after mount is applied immediately. If both leading and trailing are false, the returned value never updates.

The value is compared by reference. Passing a new object or array on every render keeps the returned value updating every wait milliseconds; stabilize the reference first, for example with usePreservedReference.

Interface

function useDebouncedValue<T>(
  value: T,
  wait: number,
  options?: DebounceOptions
): T;

Parameters

• valuerequired · T
  

  The value to debounce.

• waitrequired · number
  

  The number of milliseconds to wait after the last change before updating.

• optionsDebounceOptions
  

  Configuration options for debounce behavior.

  • options.leadingboolean · false
    

    If true, the first change after an idle period is applied immediately.

  • options.trailingboolean · true
    

    If true, the last change is applied after wait milliseconds.

Return Value

• T
  

  The debounced value.

Example

import { useDebouncedValue } from 'react-simplikit';
import { useState } from 'react';

function SearchInput() {
  const [query, setQuery] = useState('');
  const debouncedQuery = useDebouncedValue(query, 300);

  return (
    <>
      <label>
        Search
        <input value={query} onChange={e => setQuery(e.target.value)} />
      </label>
      <output aria-live="polite">{debouncedQuery}</output>
    </>
  );
}