Open History to see the last commit
1---
2title: React Rate Limiting Guide
3id: rate-limiting
4---
5
6Rate limiting allows a configured number of executions within a time window. Calls run immediately while capacity remains. Once the limit is reached, later calls are rejected until capacity becomes available again.
7
8TanStack Pacer provides an in-memory rate limiter intended primarily for client-side operations. It can run in server-side JavaScript, but it is not a distributed quota or enforcement system.
9
10## How rate limiting works
11
12This example allows three executions per window:
13
14```text
15Rate Limiting (limit: 3 calls per window)
16Timeline: [1 second per tick]
17 Window 1 | Window 2
18Calls: ⬇️ ⬇️ ⬇️ ⬇️ ⬇️ ⬇️ ⬇️
19Executed: ✅ ✅ ✅ ❌ ❌ ✅ ✅
20 [=== 3 allowed ===][=== blocked until reset ===][=== new window ===]
21```
22
23Rate limiting permits bursts. It does not space accepted calls evenly.
24
25## When to use rate limiting
26
27Choose rate limiting when:
28
29- A client operation should follow a fixed quota.
30- Calls may run immediately until the quota is exhausted.
31- Rejected calls may be discarded or handled separately.
32- You need to measure remaining capacity or time until capacity returns.
33
34Choose another utility when:
35
36- Executions should be evenly spaced. Use [throttling](./throttling.md).
37- Only the final call matters. Use [debouncing](./debouncing.md).
38- Every operation must eventually run. Use [queuing](./queuing.md).
39- Items should run together. Use [batching](./batching.md).
40- You need Promise results, retries, or abort support. Use [async rate limiting](./async-rate-limiting.md).
41
42## Window types
43
44The `windowType` option controls when capacity returns.
45
46### Fixed window
47
48A fixed window starts when its first execution is accepted. All accepted executions remain counted until that window ends. Capacity then resets together.
49
50```ts
51const limiter = useRateLimiter(sendEvent, {
52 limit: 3,
53 window: 1000,
54 windowType: 'fixed',
55})
56```
57
58Fixed windows can allow bursts near a boundary because a full quota becomes available when the window resets.
59
60### Sliding window
61
62A sliding window tracks each accepted execution separately. Capacity returns one execution at a time as old timestamps leave the window.
63
64```text
65Sliding Window (limit: 3 calls per window)
66Timeline: [1 second per tick]
67Calls: ⬇️ ⬇️ ⬇️ ⬇️ ⬇️
68Executed: ✅ ✅ ✅ ❌ ✅
69 [=== full ===][oldest execution expires][=== one available ===]
70```
71
72```ts
73const limiter = useRateLimiter(sendEvent, {
74 limit: 3,
75 window: 1000,
76 windowType: 'sliding',
77})
78```
79
80Use a sliding window when capacity should return gradually rather than all at once.
81
82## Choose an API
83
84- `useRateLimitedCallback` for a quota-controlled event handler
85- `useRateLimitedState` or `useRateLimitedValue` for React state
86- `useRateLimiter` for capacity helpers and selected state
87
88Use the callback API for operations, the state or value API for quota-controlled UI updates, and the instance API when you need capacity helpers or rejection state.
89
90## React example
91
92```tsx
93import { useRateLimiter } from '@tanstack/react-pacer'
94
95function SendButton() {
96 const limiter = useRateLimiter(
97 sendEvent,
98 { limit: 3, window: 10_000 },
99 (state) => ({
100 rejectionCount: state.rejectionCount,
101 }),
102 )
103
104 return (
105 <button onClick={() => limiter.maybeExecute('clicked')}>
106 Send ({limiter.state.rejectionCount} rejected)
107 </button>
108 )
109}
110```
111
112The focused snippets later in this guide use `useRateLimiter` and assume they run inside a component or another hook.
113
114## Handling rejected calls
115
116Rejected calls do not run later. Use the boolean return value or `onReject` to provide feedback, retry elsewhere, or place work into a queue.
117
118```ts
119const limiter = useRateLimiter(sendEvent, {
120 limit: 2,
121 window: 1000,
122 onReject: (limiter) => {
123 console.log('Rejected calls:', limiter.store.state.rejectionCount)
124 },
125})
126```
127
128If rejected operations must eventually run, a [queuer](./queuing.md) is usually a better fit.
129
130## Inspecting capacity
131
132The instance API provides two computed helpers:
133
134```ts
135limiter.getRemainingInWindow() // Accepted executions still available.
136limiter.getMsUntilNextWindow() // Time until at least one execution is available.
137```
138
139Both helpers use the current `limit`, `window`, `windowType`, and execution history.
140
141## Resetting and configuring the limiter
142
143`reset()` clears execution timestamps, counters, and cleanup timers. The next call starts with full capacity.
144
145```ts
146limiter.reset()
147```
148
149Use `setOptions()` to update the configuration:
150
151```ts
152limiter.setOptions({
153 limit: 10,
154 window: 30_000,
155})
156```
157
158Changing options does not erase existing execution history. Call `reset()` when the new configuration should begin with a fresh window.
159
160The `enabled`, `limit`, and `window` options may be functions that receive the limiter instance:
161
162```ts
163const limiter = useRateLimiter(sendEvent, {
164 enabled: (limiter) => limiter.store.state.executionCount < 100,
165 limit: (limiter) => (limiter.store.state.rejectionCount > 10 ? 2 : 5),
166 window: 60_000,
167})
168```
169
170Disabling the limiter prevents the wrapped function from executing. It does not delete existing execution history.
171
172### Observing executions
173
174`onExecute` receives the executed arguments and limiter instance. `onReject` receives the limiter instance.
175
176```ts
177const limiter = useRateLimiter(sendEvent, {
178 limit: 5,
179 window: 1000,
180 onExecute: (args, limiter) => {
181 console.log('Sent:', args)
182 console.log('Remaining:', limiter.getRemainingInWindow())
183 },
184 onReject: (limiter) => {
185 console.log('Rejected:', limiter.store.state.rejectionCount)
186 },
187})
188```
189
190## React lifecycle
191
192The adapter has no default operation cleanup because a synchronous limiter has no pending or active work. Use `onUnmount` only when the component needs custom teardown related to the limiter.
193
194## Reactive state
195
196The adapter subscribes only to the state returned by the selector argument. Without a selector, the adapter state is empty. Create the utility at the top level of a component or another hook and select only fields used by the view:
197
198```ts
199const limiter = useRateLimiter(
200 sendEvent,
201 { limit: 5, window: 60_000 },
202 (state) => ({
203 isExceeded: state.isExceeded,
204 rejectionCount: state.rejectionCount,
205 }),
206)
207
208console.log(limiter.state.isExceeded, limiter.state.rejectionCount)
209```
210
211Option functions and lifecycle callbacks receive the underlying public utility instance. The `.store.state` reads inside those callbacks in the examples above are supported. Rendering code should read the selected adapter state shown here.
212
213To restore selected state that your app has persisted, pass a partial snapshot through `initialState`. It is merged with the defaults. Restore only durable fields. Pending timers are not restored.
214
215Commonly useful state includes:
216
217- `executionCount`: Total accepted executions that completed.
218- `executionTimes`: Timestamps currently used for window calculations.
219- `isExceeded`: Whether the current limit has been reached.
220- `rejectionCount`: Calls rejected because the window was full.
221- `status`: `'disabled'`, `'exceeded'`, or `'idle'`.
222
223See the [React API reference](../reference/index.md) for adapter signatures and the public core reference for complete option and state types.