Skip to content
Source
Sign inSign up
TanStack/pacer
Open History to see the last commit

useAsyncThrottledCallback.md

67 lines2.1 KB

1---
2id: useAsyncThrottledCallback
3title: useAsyncThrottledCallback
4---
5​
6```ts
7function useAsyncThrottledCallback<TFn>(fn, options): (...args) => Promise<Awaited<ReturnType<TFn>> | undefined>;
8```
9​
10Defined in: [async-throttler/useAsyncThrottledCallback.ts:43](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/async-throttler/useAsyncThrottledCallback.ts#L43)
11​
12A React hook that creates a throttled version of an async callback function.
13This hook is a convenient wrapper around the `useAsyncThrottler` hook,
14providing a stable, throttled async function reference for use in React components.
15​
16The throttled async function will execute at most once within the specified wait time period,
17regardless of how many times it is called. Calls made during the wait period reschedule a
18single trailing execution with the latest arguments when `trailing` is enabled (the default).
19The most recent call's promise resolves or rejects with the trailing execution's result;
20each earlier call's promise resolves immediately with the most recent previous result (or
21`undefined` if nothing has executed yet), as does every call when the throttler is disabled.
22​
23This hook provides a simpler API compared to `useAsyncThrottler`, making it ideal for basic
24async throttling needs. However, it does not expose the underlying AsyncThrottler instance.
25​
26For advanced usage requiring features like:
27- Manual cancellation
28- Access to execution/error state
29- Custom useCallback dependencies
30​
31Consider using the `useAsyncThrottler` hook instead.
32​
33## Type Parameters
34​
35### TFn
36​
37`TFn` *extends* `AnyAsyncFunction`
38​
39## Parameters
40​
41### fn
42​
43`TFn`
44​
45### options
46​
47[`ReactAsyncThrottlerOptions`](../interfaces/ReactAsyncThrottlerOptions.md)\<`TFn`, \{
48\}\>
49​
50## Returns
51​
52(...`args`) => `Promise`\<`Awaited`\<`ReturnType`\<`TFn`\>\> \| `undefined`\>
53​
54## Example
55​
56```tsx
57// Throttle an async API call
58const handleApiCall = useAsyncThrottledCallback(async (data) => {
59 const result = await sendDataToServer(data);
60 return result;
61}, {
62 wait: 200 // Execute at most once every 200ms
63});
64​
65// Use in an event handler
66<button onClick={() => handleApiCall(formData)}>Send</button>
67```