Open History to see the last commit
1---
2title: React Queuing Guide
3id: queuing
4---
5
6Queuing stores operations in an ordered buffer and processes them individually. It is the primary Pacer strategy for work that should not be discarded when calls arrive faster than they can run.
7
8Queues are lossless only while they have capacity. A finite `maxSize`, explicit clearing, expiration, or a processing error can still remove or reject work.
9
10## How queuing works
11
12```text
13Queuing (process one item every 2 ticks)
14Timeline: [1 second per tick]
15Calls: ⬇️ ⬇️ ⬇️ ⬇️ ⬇️ ⬇️ ⬇️ ⬇️
16Queue: [ABC] [BC] [BCDE] [DE] [E] []
17Executed: ✅ ✅ ✅ ✅ ✅ ✅
18 [======================================================]
19 ^ Accepted items remain queued until processed
20
21 [Items arrive] [Process steadily] [Empty]
22```
23
24The queue can process automatically with a delay between items, or remain stopped for manual processing.
25
26## When to use queuing
27
28Choose queuing when:
29
30- Every accepted operation should run individually.
31- Processing order matters.
32- Incoming work may temporarily exceed processing capacity.
33- A maximum buffer size should reject excess work explicitly.
34- FIFO, LIFO, or priority ordering is required.
35
36Choose another utility when:
37
38- Only the final call matters. Use [debouncing](./debouncing.md).
39- Intermediate calls may be discarded while work runs steadily. Use [throttling](./throttling.md).
40- Calls should be rejected after a time-window quota. Use [rate limiting](./rate-limiting.md).
41- Items should run together. Use [batching](./batching.md).
42- Tasks return Promises or should run concurrently. Use [async queuing](./async-queuing.md).
43
44## Choose an API
45
46- `useQueuedState` or `useQueuedValue` for a queue connected to React state
47- `useQueuer` for direct queue lifecycle and ordering control
48
49Use the queued state or value API when queue contents drive the UI. Use the instance API for ordering, capacity, expiration, pause, resume, flush, and manual processing.
50
51## React example
52
53```tsx
54import { useQueuedState } from '@tanstack/react-pacer'
55
56function JobQueue() {
57 const [items, addItem, queue] = useQueuedState(
58 processJob,
59 { wait: 500 },
60 (state) => ({
61 items: state.items,
62 isRunning: state.isRunning,
63 }),
64 )
65
66 return (
67 <>
68 <button onClick={() => addItem(nextJob())}>Add job</button>
69 <button
70 onClick={() => (queue.state.isRunning ? queue.stop() : queue.start())}
71 >
72 {queue.state.isRunning ? 'Pause' : 'Resume'} ({items.length})
73 </button>
74 </>
75 )
76}
77```
78
79The focused snippets later in this guide use `useQueuer` and assume they run inside a component or another hook.
80
81Pass `initialItems` when work is already available at creation time. The queue applies its normal insertion and capacity rules, and automatic processing can begin immediately unless `started: false` is set.
82
83## Ordering items
84
85Automatic processing uses `addItemsTo` to choose where new items enter and `getItemsFrom` to choose where items leave.
86
87### FIFO
88
89FIFO processes the oldest item first. This is the default.
90
91```ts
92const queuer = useQueuer(processItem, {
93 addItemsTo: 'back',
94 getItemsFrom: 'front',
95 started: false,
96})
97
98queuer.addItem(1)
99queuer.addItem(2)
100queuer.addItem(3)
101queuer.start() // Processes 1, 2, 3.
102```
103
104### LIFO
105
106LIFO processes the newest item first.
107
108```ts
109const queuer = useQueuer(processItem, {
110 addItemsTo: 'back',
111 getItemsFrom: 'back',
112 started: false,
113})
114
115queuer.addItem(1)
116queuer.addItem(2)
117queuer.addItem(3)
118queuer.start() // Processes 3, 2, 1.
119```
120
121### Priority
122
123Provide `getPriority` to process higher numeric priorities first. Priority ordering takes precedence over front and back retrieval.
124
125```ts
126type Task = { name: string; priority: number }
127
128const queuer = useQueuer<Task>(processTask, {
129 getPriority: (task) => task.priority,
130 started: false,
131})
132
133queuer.addItem({ name: 'low', priority: 1 })
134queuer.addItem({ name: 'high', priority: 3 })
135queuer.addItem({ name: 'medium', priority: 2 })
136queuer.start() // Processes high, medium, low.
137```
138
139## Automatic and manual processing
140
141Queues start automatically by default. The first accepted item processes immediately, then `wait` controls the delay before later items.
142
143```ts
144const queuer = useQueuer(processItem, {
145 wait: 1000,
146})
147```
148
149Set `started: false` to collect items before processing:
150
151```ts
152const queuer = useQueuer(processItem, { started: false })
153
154queuer.addItem(1)
155queuer.addItem(2)
156queuer.start()
157queuer.stop()
158```
159
160`stop()` cancels the scheduled tick and retains queued items. `start()` resumes automatic processing.
161
162For manual control:
163
164- `execute()` removes and processes the next item immediately.
165- `getNextItem()` removes and returns the next item without processing it.
166- `peekNextItem()` returns the next item without removing it.
167- `peekAllItems()` returns a copy of the current queue.
168
169## Capacity and rejection
170
171Set `maxSize` to bound the number of waiting items. An item added to a full queue is rejected, `addItem()` returns `false`, and `onReject` runs.
172
173```ts
174const queuer = useQueuer(processItem, {
175 maxSize: 2,
176 started: false,
177 onReject: (item, queuer) => {
178 console.log('Rejected:', item)
179 console.log('Total rejections:', queuer.store.state.rejectionCount)
180 },
181})
182
183queuer.addItem(1) // true
184queuer.addItem(2) // true
185queuer.addItem(3) // false
186```
187
188The active synchronous execution is not part of `size`; `size` counts items still waiting in the queue.
189
190## Expiring stale items
191
192Use `expirationDuration` to remove items that have waited too long:
193
194```ts
195const queuer = useQueuer(processItem, {
196 expirationDuration: 5000,
197 onExpire: (item) => {
198 console.log('Expired:', item)
199 },
200})
201```
202
203Use `getIsExpired` for custom logic:
204
205```ts
206const queuer = useQueuer(processItem, {
207 getIsExpired: (item, addedAt) => Date.now() - addedAt > item.maxAge,
208})
209```
210
211Expiration is checked while the automatic processing loop runs. A stopped queue evaluates stale items when processing resumes.
212
213## Flushing, clearing, and resetting
214
215### Flush
216
217`flush()` processes waiting items immediately without the configured delay. Pass a count to process only part of the queue.
218
219```ts
220queuer.flush() // Process all waiting items.
221queuer.flush(2) // Process at most two waiting items.
222```
223
224`flushAsBatch()` removes all waiting items and passes them to a separate batch function:
225
226```ts
227queuer.flushAsBatch((items) => {
228 saveItems(items)
229})
230```
231
232### Clear
233
234`clear()` removes all waiting items without processing them. It does not change whether the queue is running.
235
236```ts
237queuer.clear()
238```
239
240### Reset
241
242`reset()` restores state to the default running, empty queue. It does not clear an already scheduled timeout. Call `stop()` before `reset()` when scheduled work must be canceled.
243
244```ts
245queuer.stop()
246queuer.reset()
247```
248
249## Configuring and observing the queue
250
251Use `setOptions()` to update future behavior. Changing `started` through `setOptions()` does not call `start()` or `stop()`.
252
253```ts
254queuer.setOptions({ wait: 250, maxSize: 20 })
255queuer.start()
256```
257
258The `wait` option may be a function that receives the queuer instance:
259
260```ts
261const queuer = useQueuer(processItem, {
262 wait: (queuer) => (queuer.store.state.size > 20 ? 50 : 250),
263})
264```
265
266Use callbacks for queue events:
267
268- `onItemsChange`: An item was added or removed.
269- `onExecute`: An item was processed.
270- `onReject`: An item was rejected.
271- `onExpire`: An item expired.
272
273## React lifecycle
274
275The adapter stops automatic processing 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.
276
277## Reactive state
278
279The 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:
280
281```ts
282const queuer = useQueuer(processItem, { wait: 250 }, (state) => ({
283 size: state.size,
284 isRunning: state.isRunning,
285}))
286
287console.log(queuer.state.size, queuer.state.isRunning)
288```
289
290Option 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.
291
292`initialState` can restore selected queue state that your app has persisted. If it includes `items`, they take precedence over `initialItems`; `initialState.isRunning` likewise takes precedence over `started`. Restore only durable fields. Pending timers are not restored.
293
294Commonly useful state includes:
295
296- `items` and `size`: Items still waiting.
297- `isRunning`: Whether automatic processing is enabled.
298- `isIdle`: Whether a running queue is empty.
299- `isFull`: Whether `maxSize` has been reached.
300- `executionCount`: Items whose wrapped function returned successfully.
301- `rejectionCount` and `expirationCount`: Items removed without processing.
302- `status`: `'idle'`, `'running'`, or `'stopped'`.
303
304See the [React API reference](../reference/index.md) for adapter signatures and the public core reference for complete option and state types.