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

useRateLimitedCallback.md

84 lines2.7 KB

1---
2id: useRateLimitedCallback
3title: useRateLimitedCallback
4---
5​
6```ts
7function useRateLimitedCallback<TFn>(fn, options): (...args) => boolean;
8```
9​
10Defined in: [rate-limiter/useRateLimitedCallback.ts:59](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/rate-limiter/useRateLimitedCallback.ts#L59)
11​
12A React hook that creates a rate-limited version of a callback function.
13This hook is essentially a wrapper around the basic `rateLimiter` function
14that is exported from `@tanstack/pacer`,
15but optimized for React with reactive options and a stable function reference.
16​
17Rate limiting is a simple "hard limit" approach - it allows all calls until the limit
18is reached, then blocks subsequent calls until the window resets. Unlike throttling
19or debouncing, it does not attempt to space out or intelligently collapse calls.
20This can lead to bursts of rapid executions followed by periods where all calls
21are blocked.
22​
23The rate limiter supports two types of windows:
24- 'fixed': A strict window that resets after the window period. All executions within the window count
25 towards the limit, and the window resets completely after the period.
26- 'sliding': A rolling window that allows executions as old ones expire. This provides a more
27 consistent rate of execution over time.
28​
29For smoother execution patterns, consider:
30- useThrottledCallback: When you want consistent spacing between executions (e.g. UI updates)
31- useDebouncedCallback: When you want to collapse rapid calls into a single execution (e.g. search input)
32​
33Rate limiting should primarily be used when you need to enforce strict limits,
34like API rate limits or other scenarios requiring hard caps on execution frequency.
35​
36This hook provides a simpler API compared to `useRateLimiter`, making it ideal for basic
37rate limiting needs. However, it does not expose the underlying RateLimiter instance.
38​
39For advanced usage requiring features like:
40- Manual cancellation
41- Access to execution counts
42- Custom useCallback dependencies
43​
44Consider using the `useRateLimiter` hook instead.
45​
46## Type Parameters
47​
48### TFn
49​
50`TFn` *extends* `AnyFunction`
51​
52## Parameters
53​
54### fn
55​
56`TFn`
57​
58### options
59​
60[`ReactRateLimiterOptions`](../interfaces/ReactRateLimiterOptions.md)\<`TFn`, \{
61\}\>
62​
63## Returns
64​
65(...`args`) => `boolean`
66​
67## Example
68​
69```tsx
70// Rate limit API calls to maximum 5 calls per minute with a sliding window
71const makeApiCall = useRateLimitedCallback(
72 (data: ApiData) => {
73 return fetch('/api/endpoint', { method: 'POST', body: JSON.stringify(data) });
74 },
75 {
76 limit: 5,
77 window: 60000, // 1 minute
78 windowType: 'sliding',
79 onReject: () => {
80 console.warn('API rate limit reached. Please wait before trying again.');
81 }
82 }
83);
84```