Open History to see the last commit
1---
2id: useQueuedValue
3title: useQueuedValue
4---
5
6```ts
7function useQueuedValue<TValue, TSelected>(
8 initialValue,
9 options?,
10 selector?): [TValue, ReactQueuer<TValue, TSelected>];
11```
12
13Defined in: [queuer/useQueuedValue.ts:103](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/queuer/useQueuedValue.ts#L103)
14
15A React hook that creates a queued value that processes state changes in order with an optional delay.
16This hook uses useQueuer internally to manage a queue of state changes and apply them sequentially.
17
18The queued value will process changes in the order they are received, with optional delays between
19processing each change. This is useful for handling state updates that need to be processed
20in a specific order, like animations or sequential UI updates.
21
22The hook returns a tuple containing:
23- The current queued value
24- The queuer instance with control methods
25
26## State Management and Selector
27
28The hook uses TanStack Store for reactive state management via the underlying queuer instance.
29The `selector` parameter allows you to specify which queuer state changes will trigger a re-render,
30optimizing performance by preventing unnecessary re-renders when irrelevant state changes occur.
31
32**By default, there will be no reactive state subscriptions** and you must opt-in to state
33tracking by providing a selector function. This prevents unnecessary re-renders and gives you
34full control over when your component updates. Only when you provide a selector will the
35component re-render when the selected state values change.
36
37Available queuer state properties:
38- `executionCount`: Number of items that have been processed by the queuer
39- `expirationCount`: Number of items that have been removed due to expiration
40- `isEmpty`: Whether the queuer has no items to process
41- `isFull`: Whether the queuer has reached its maximum capacity
42- `isIdle`: Whether the queuer is not currently processing any items
43- `isRunning`: Whether the queuer is active and will process items automatically
44- `items`: Array of items currently waiting to be processed
45- `itemTimestamps`: Timestamps when items were added for expiration tracking
46- `pendingTick`: Whether the queuer has a pending timeout for processing the next item
47- `rejectionCount`: Number of items that have been rejected from being added
48- `size`: Number of items currently in the queue
49- `status`: Current processing status ('idle' | 'running' | 'stopped')
50
51## Type Parameters
52
53### TValue
54
55`TValue`
56
57### TSelected
58
59`TSelected` *extends* `Pick`\<`QueuerState`\<`TValue`\>, `"items"`\> = `Pick`\<`QueuerState`\<`TValue`\>, `"items"`\>
60
61## Parameters
62
63### initialValue
64
65`TValue`
66
67### options?
68
69[`ReactQueuerOptions`](../interfaces/ReactQueuerOptions.md)\<`TValue`, `TSelected`\> = `{}`
70
71### selector?
72
73(`state`) => `TSelected`
74
75## Returns
76
77\[`TValue`, [`ReactQueuer`](../interfaces/ReactQueuer.md)\<`TValue`, `TSelected`\>\]
78
79## Example
80
81```tsx
82// Default behavior - no reactive state subscriptions
83const [value, queuer] = useQueuedValue(initialValue, {
84 wait: 500, // Wait 500ms between processing each change
85 started: true // Start processing immediately
86});
87
88// Opt-in to re-render when queue processing state changes (optimized for loading indicators)
89const [value, queuer] = useQueuedValue(
90 initialValue,
91 { wait: 500, started: true },
92 (state) => ({
93 isRunning: state.isRunning,
94 isIdle: state.isIdle,
95 status: state.status,
96 pendingTick: state.pendingTick
97 })
98);
99
100// Opt-in to re-render when queue contents change (optimized for displaying queue status)
101const [value, queuer] = useQueuedValue(
102 initialValue,
103 { wait: 500, started: true },
104 (state) => ({
105 size: state.size,
106 isEmpty: state.isEmpty,
107 isFull: state.isFull
108 })
109);
110
111// Opt-in to re-render when execution metrics change (optimized for stats display)
112const [value, queuer] = useQueuedValue(
113 initialValue,
114 { wait: 500, started: true },
115 (state) => ({
116 executionCount: state.executionCount,
117 expirationCount: state.expirationCount,
118 rejectionCount: state.rejectionCount
119 })
120);
121
122// Add changes to the queue
123const handleChange = (newValue) => {
124 queuer.addItem(newValue);
125};
126
127// Control the queue
128const pauseProcessing = () => {
129 queuer.stop();
130};
131
132const resumeProcessing = () => {
133 queuer.start();
134};
135
136// Access the selected queuer state (will be empty object {} unless selector provided)
137const { size, isRunning, executionCount } = queuer.state;
138```