Open History to see the last commit
1---
2title: React Batching Guide
3id: batching
4---
5
6Batching collects items and passes them to one function as an array. A batch can run when it reaches a configured size, after no new items arrive for a configured wait, or when custom logic says it is ready.
7
8Batching reduces the number of operations by processing several items together. Unlike queuing, it does not call the wrapped function once for each item.
9
10## How batching works
11
12```text
13Batching (process every 3 items or after 2 quiet ticks)
14Timeline: [1 second per tick]
15Calls: ⬇️ ⬇️ ⬇️ ⬇️ ⬇️ ⬇️ ⬇️ ⬇️
16Batch: [ABC] [] [DE] [] [FGH] []
17Executed: ✅ ✅ ✅
18 [======================================================]
19 ^ Items are grouped and processed together
20
21 [Size reached] [Wait elapsed] [Size reached]
22```
23
24Each execution receives a copy of the items currently collected. The batcher clears those items before calling the wrapped function.
25
26## When to use batching
27
28Choose batching when:
29
30- A bulk operation is more efficient than individual operations.
31- Network requests, database writes, or analytics events can be grouped.
32- A maximum batch size or quiet-period trigger matches the workload.
33- Individual item results are unnecessary.
34
35Choose another utility when:
36
37- Every item should run individually and in order. Use [queuing](./queuing.md).
38- Only the latest value matters. Use [debouncing](./debouncing.md).
39- Calls should be spaced over time. Use [throttling](./throttling.md).
40- Batch processing returns a Promise or needs retries and abort support. Use [async batching](./async-batching.md).
41
42## Choose an API
43
44- `useBatchedCallback` for a stable item-adder
45- `useBatcher` for flush, cancel, collected items, and selected state
46
47Use the callback API when adding items is all the component needs. Use the instance API for `flush()`, `cancel()`, collected items, selected state, and dynamic options.
48
49## React example
50
51```tsx
52import { useBatcher } from '@tanstack/react-pacer'
53
54function AnalyticsButton() {
55 const batcher = useBatcher(
56 sendEvents,
57 { maxSize: 20, wait: 1000 },
58 (state) => ({
59 size: state.size,
60 }),
61 )
62
63 return (
64 <button onClick={() => batcher.addItem({ type: 'click' })}>
65 Track ({batcher.state.size} pending)
66 </button>
67 )
68}
69```
70
71The focused snippets later in this guide use `useBatcher` and assume they run inside a component or another hook.
72
73## Choosing batch triggers
74
75### Batch size
76
77`maxSize` executes the batch as soon as the number of collected items reaches the limit.
78
79```ts
80const batcher = useBatcher(processBatch, {
81 maxSize: 100,
82})
83```
84
85The default is `Infinity`, so a size trigger is disabled unless you provide one.
86
87### Wait time
88
89`wait` executes a batch after no new items arrive for the configured duration. Every added item restarts the timer.
90
91```ts
92const batcher = useBatcher(processBatch, {
93 wait: 1000,
94})
95```
96
97The default is `Infinity`, so a time trigger is disabled unless you provide one. A continuous stream of items can keep restarting the timer. Combine `wait` with `maxSize` when a batch must eventually run under continuous traffic.
98
99### Custom trigger
100
101`getShouldExecute` runs after each item is added. Return `true` to execute the current batch immediately.
102
103```ts
104const batcher = useBatcher<number>(processBatch, {
105 getShouldExecute: (items) => items.includes(0),
106})
107
108batcher.addItem(4)
109batcher.addItem(0) // Executes [4, 0].
110```
111
112If several triggers are configured, the first one reached executes the batch.
113
114## Controlling collected items
115
116### Flush
117
118`flush()` clears the pending timer and executes all currently collected items. It does nothing when the batch is empty.
119
120```ts
121batcher.addItem('event-1')
122batcher.addItem('event-2')
123batcher.flush()
124```
125
126### Cancel
127
128`cancel()` clears the pending timer but keeps the collected items. A later item can schedule a new timer, or you can call `flush()`.
129
130```ts
131batcher.cancel()
132console.log(batcher.peekAllItems()) // Items are still present.
133```
134
135### Clear
136
137`clear()` removes all collected items. It does not clear the timer itself, although that timer has no items to execute unless more items are added.
138
139```ts
140batcher.clear()
141```
142
143### Reset
144
145`reset()` restores batch state and counters to their defaults. It does not cancel an already scheduled timer. Call `cancel()` before `reset()` when pending work must be discarded.
146
147```ts
148batcher.cancel()
149batcher.reset()
150```
151
152## Configuring and observing batches
153
154Use `setOptions()` to update future trigger behavior:
155
156```ts
157batcher.setOptions({
158 maxSize: 20,
159 wait: 500,
160})
161```
162
163Changing `wait` does not reschedule an existing timer. The next `addItem()` call replaces that timer using the current value.
164
165The `wait` option may be a function that receives the batcher instance:
166
167```ts
168const batcher = useBatcher(processBatch, {
169 wait: (batcher) => (batcher.store.state.size > 10 ? 100 : 500),
170})
171```
172
173Use `onItemsChange` to observe collection changes and `onExecute` to observe completed batch calls:
174
175```ts
176const batcher = useBatcher(processBatch, {
177 maxSize: 10,
178 onItemsChange: (batcher) => {
179 console.log('Collected:', batcher.store.state.size)
180 },
181 onExecute: (items, batcher) => {
182 console.log('Processed:', items)
183 console.log('Batches:', batcher.store.state.executionCount)
184 },
185})
186```
187
188Do not use `started` to pause a batcher. It is currently a no-op, so every `addItem()` call evaluates the configured triggers.
189
190## React lifecycle
191
192The adapter cancels the pending wait timer while retaining collected items when its owner is destroyed. Providing `onUnmount` replaces that default cleanup, so a custom callback must perform every required lifecycle action. When custom cleanup flushes work, remember that user callbacks can run while the component is being destroyed.
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 batcher = useBatcher(
200 processBatch,
201 { maxSize: 20, wait: 1000 },
202 (state) => ({
203 size: state.size,
204 isPending: state.isPending,
205 }),
206)
207
208console.log(batcher.state.size, batcher.state.isPending)
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- `items`: Items currently collected.
218- `size`: Number of collected items.
219- `isEmpty`: Whether the batch is empty.
220- `isPending`: Whether a wait timer is active.
221- `executionCount`: Completed batch executions.
222- `totalItemsProcessed`: Items passed to completed batch executions.
223- `status`: `'idle'` or `'pending'`.
224
225See the [React API reference](../reference/index.md) for adapter signatures and the public core reference for complete option and state types.