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

useQueuedValue.md

138 lines4.4 KB

1---
2id: useQueuedValue
3title: useQueuedValue
4---
5​
6```ts
7function useQueuedValue<TValue, TSelected>(
8 initialValue,
9 options?,
10 selector?): [TValue, PreactQueuer<TValue, TSelected>];
11```
12​
13Defined in: [queuer/useQueuedValue.ts:103](https://github.com/TanStack/pacer/blob/main/packages/preact-pacer/src/queuer/useQueuedValue.ts#L103)
14​
15A Preact 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[`PreactQueuerOptions`](../interfaces/PreactQueuerOptions.md)\<`TValue`, `TSelected`\> = `{}`
70​
71### selector?
72​
73(`state`) => `TSelected`
74​
75## Returns
76​
77\[`TValue`, [`PreactQueuer`](../interfaces/PreactQueuer.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```