useAsyncDebouncer
Function: useAsyncDebouncer()
function useAsyncDebouncer<TFn, TSelected>(
fn,
options,
selector?): ReactAsyncDebouncer<TFn, TSelected>
function useAsyncDebouncer<TFn, TSelected>(
fn,
options,
selector?): ReactAsyncDebouncer<TFn, TSelected>
Defined in: react-pacer/src/async-debouncer/useAsyncDebouncer.ts:141
A low-level React hook that creates an AsyncDebouncer instance to delay execution of an async function.
This hook is designed to be flexible and state-management agnostic - it simply returns a debouncer instance that you can integrate with any state management solution (useState, Redux, Zustand, Jotai, etc).
Async debouncing ensures that an async function only executes after a specified delay has passed since its last invocation. Each new invocation resets the delay timer. This is useful for handling frequent events like window resizing or input changes where you only want to execute the handler after the events have stopped occurring.
Unlike throttling which allows execution at regular intervals, debouncing prevents any execution until the function stops being called for the specified delay period.
Unlike the non-async Debouncer, this async version supports returning values from the debounced function, making it ideal for API calls and other async operations where you want the result of the maybeExecute call instead of setting the result on a state variable from within the debounced function.
Error Handling:
- If an onError handler is provided, it will be called with the error and debouncer instance
- If throwOnError is true (default when no onError handler is provided), the error will be thrown
- If throwOnError is false (default when onError handler is provided), the error will be swallowed
- Both onError and throwOnError can be used together - the handler will be called before any error is thrown
- The error state can be checked using the underlying AsyncDebouncer instance
State Management and Selector
The hook uses TanStack Store for reactive state management. The selector parameter allows you to specify which state changes will trigger a re-render, optimizing performance by preventing unnecessary re-renders when irrelevant state changes occur.
By default, all 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 state properties:
- canLeadingExecute: Whether the debouncer can execute on the leading edge
- errorCount: Number of function executions that have resulted in errors
- isExecuting: Whether the debounced function is currently executing asynchronously
- isPending: Whether the debouncer is waiting for the timeout to trigger execution
- lastArgs: The arguments from the most recent call to maybeExecute
- lastResult: The result from the most recent successful function execution
- settleCount: Number of function executions that have completed (success or error)
- status: Current execution status ('disabled' | 'idle' | 'pending' | 'executing' | 'settled')
- successCount: Number of function executions that have completed successfully
Type Parameters
• TFn extends AnyAsyncFunction
• TSelected = AsyncDebouncerState<TFn>
Parameters
fn
TFn
options
AsyncDebouncerOptions<TFn>
selector?
(state) => TSelected
Returns
ReactAsyncDebouncer<TFn, TSelected>
Example
// Basic API call debouncing - re-renders on any state change
const searchDebouncer = useAsyncDebouncer(
async (query: string) => {
const results = await api.search(query);
return results;
},
{ wait: 500 }
);
// Only re-render when execution state changes (optimized for loading indicators)
const searchDebouncer = useAsyncDebouncer(
async (query: string) => {
const results = await api.search(query);
return results;
},
{ wait: 500 },
(state) => ({
isExecuting: state.isExecuting,
isPending: state.isPending
})
);
// Only re-render when results are available (optimized for data display)
const searchDebouncer = useAsyncDebouncer(
async (query: string) => {
const results = await api.search(query);
return results;
},
{ wait: 500 },
(state) => ({
lastResult: state.lastResult,
successCount: state.successCount
})
);
// Only re-render when error state changes (optimized for error handling)
const searchDebouncer = useAsyncDebouncer(
async (query: string) => {
const results = await api.search(query);
return results;
},
{
wait: 500,
onError: (error) => console.error('Search failed:', error)
},
(state) => ({
errorCount: state.errorCount,
status: state.status
})
);
// With state management
const [results, setResults] = useState([]);
const { maybeExecute, state } = useAsyncDebouncer(
async (searchTerm) => {
const data = await searchAPI(searchTerm);
setResults(data);
},
{
wait: 300,
leading: true, // Execute immediately on first call
trailing: false, // Skip trailing edge updates
onError: (error) => {
console.error('API call failed:', error);
}
}
);
// Access the selected state
const { isExecuting, lastResult } = state;
// Basic API call debouncing - re-renders on any state change
const searchDebouncer = useAsyncDebouncer(
async (query: string) => {
const results = await api.search(query);
return results;
},
{ wait: 500 }
);
// Only re-render when execution state changes (optimized for loading indicators)
const searchDebouncer = useAsyncDebouncer(
async (query: string) => {
const results = await api.search(query);
return results;
},
{ wait: 500 },
(state) => ({
isExecuting: state.isExecuting,
isPending: state.isPending
})
);
// Only re-render when results are available (optimized for data display)
const searchDebouncer = useAsyncDebouncer(
async (query: string) => {
const results = await api.search(query);
return results;
},
{ wait: 500 },
(state) => ({
lastResult: state.lastResult,
successCount: state.successCount
})
);
// Only re-render when error state changes (optimized for error handling)
const searchDebouncer = useAsyncDebouncer(
async (query: string) => {
const results = await api.search(query);
return results;
},
{
wait: 500,
onError: (error) => console.error('Search failed:', error)
},
(state) => ({
errorCount: state.errorCount,
status: state.status
})
);
// With state management
const [results, setResults] = useState([]);
const { maybeExecute, state } = useAsyncDebouncer(
async (searchTerm) => {
const data = await searchAPI(searchTerm);
setResults(data);
},
{
wait: 300,
leading: true, // Execute immediately on first call
trailing: false, // Skip trailing edge updates
onError: (error) => {
console.error('API call failed:', error);
}
}
);
// Access the selected state
const { isExecuting, lastResult } = state;
Subscribe to Bytes
Your weekly dose of JavaScript news. Delivered every Monday to over 100,000 devs, for free.