Framework
Version
Debouncer API Reference
Throttler API Reference
Rate Limiter API Reference
Queue API Reference
Batcher API Reference

useDebouncedValue

Function: useDebouncedValue()

ts
function useDebouncedValue<TValue, TSelected>(
   value, 
   options, 
   selector?): [TValue, ReactDebouncer<Dispatch<SetStateAction<TValue>>, TSelected>]
function useDebouncedValue<TValue, TSelected>(
   value, 
   options, 
   selector?): [TValue, ReactDebouncer<Dispatch<SetStateAction<TValue>>, TSelected>]

Defined in: react-pacer/src/debouncer/useDebouncedValue.ts:89

A React hook that creates a debounced value that updates only after a specified delay. Unlike useDebouncedState, this hook automatically tracks changes to the input value and updates the debounced value accordingly.

The debounced value will only update after the specified wait time has elapsed since the last change to the input value. If the input value changes again before the wait time expires, the timer resets and starts waiting again.

This is useful for deriving debounced values from props or state that change frequently, like search queries or form inputs, where you want to limit how often downstream effects or calculations occur.

The hook returns the current debounced value and the underlying debouncer instance. The debouncer instance can be used to access additional functionality like cancellation and execution counts.

State Management and Selector

The hook uses TanStack Store for reactive state management via the underlying debouncer instance. The selector parameter allows you to specify which debouncer state changes will trigger a re-render, optimizing performance by preventing unnecessary re-renders when irrelevant state changes occur.

By default, all debouncer state changes will trigger a re-render. To optimize performance, you can provide a selector function that returns only the specific state values your component needs. The component will only re-render when the selected values change.

Available debouncer state properties:

  • canLeadingExecute: Whether the debouncer can execute on the leading edge
  • executionCount: Number of function executions that have been completed
  • isPending: Whether the debouncer is waiting for the timeout to trigger execution
  • lastArgs: The arguments from the most recent call to maybeExecute
  • status: Current execution status ('disabled' | 'idle' | 'pending')

Type Parameters

TValue

TSelected = DebouncerState<Dispatch<SetStateAction<TValue>>>

Parameters

value

TValue

options

DebouncerOptions<Dispatch<SetStateAction<TValue>>>

selector?

(state) => TSelected

Returns

[TValue, ReactDebouncer<Dispatch<SetStateAction<TValue>>, TSelected>]

Example

tsx
// Debounce a search query (re-renders on any debouncer state change)
const [searchQuery, setSearchQuery] = useState('');
const [debouncedQuery, debouncer] = useDebouncedValue(searchQuery, {
  wait: 500 // Wait 500ms after last change
});

// Only re-render when pending state changes (optimized for loading indicators)
const [debouncedQuery, debouncer] = useDebouncedValue(
  searchQuery,
  { wait: 500 },
  (state) => ({ isPending: state.isPending })
);

// Only re-render when execution count changes (optimized for tracking executions)
const [debouncedQuery, debouncer] = useDebouncedValue(
  searchQuery,
  { wait: 500 },
  (state) => ({ executionCount: state.executionCount })
);

// Only re-render when debouncing status changes (optimized for status display)
const [debouncedQuery, debouncer] = useDebouncedValue(
  searchQuery,
  { wait: 500 },
  (state) => ({
    status: state.status,
    canLeadingExecute: state.canLeadingExecute
  })
);

// debouncedQuery will update 500ms after searchQuery stops changing
useEffect(() => {
  fetchSearchResults(debouncedQuery);
}, [debouncedQuery]);

// Handle input changes
const handleChange = (e) => {
  setSearchQuery(e.target.value);
};

// Access the selected debouncer state
const { isPending, executionCount } = debouncer.state;
// Debounce a search query (re-renders on any debouncer state change)
const [searchQuery, setSearchQuery] = useState('');
const [debouncedQuery, debouncer] = useDebouncedValue(searchQuery, {
  wait: 500 // Wait 500ms after last change
});

// Only re-render when pending state changes (optimized for loading indicators)
const [debouncedQuery, debouncer] = useDebouncedValue(
  searchQuery,
  { wait: 500 },
  (state) => ({ isPending: state.isPending })
);

// Only re-render when execution count changes (optimized for tracking executions)
const [debouncedQuery, debouncer] = useDebouncedValue(
  searchQuery,
  { wait: 500 },
  (state) => ({ executionCount: state.executionCount })
);

// Only re-render when debouncing status changes (optimized for status display)
const [debouncedQuery, debouncer] = useDebouncedValue(
  searchQuery,
  { wait: 500 },
  (state) => ({
    status: state.status,
    canLeadingExecute: state.canLeadingExecute
  })
);

// debouncedQuery will update 500ms after searchQuery stops changing
useEffect(() => {
  fetchSearchResults(debouncedQuery);
}, [debouncedQuery]);

// Handle input changes
const handleChange = (e) => {
  setSearchQuery(e.target.value);
};

// Access the selected debouncer state
const { isPending, executionCount } = debouncer.state;
Our Partners
Unkey
Subscribe to Bytes

Your weekly dose of JavaScript news. Delivered every Monday to over 100,000 devs, for free.

Bytes

No spam. Unsubscribe at any time.

Subscribe to Bytes

Your weekly dose of JavaScript news. Delivered every Monday to over 100,000 devs, for free.

Bytes

No spam. Unsubscribe at any time.