Open History to see the last commit
1---
2id: useThrottledState
3title: useThrottledState
4---
5
6```ts
7function useThrottledState<TValue, TSelected>(
8 value,
9 options,
10 selector?): [TValue, Dispatch<SetStateAction<TValue>>, ReactThrottler<Dispatch<SetStateAction<TValue>>, TSelected>];
11```
12
13Defined in: [throttler/useThrottledState.ts:90](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/throttler/useThrottledState.ts#L90)
14
15A React hook that creates a throttled state value that updates at most once within a specified time window.
16This hook combines React's useState with throttling functionality to provide controlled state updates.
17
18Throttling ensures state updates occur at a controlled rate regardless of how frequently the setter is called.
19This is useful for rate-limiting expensive re-renders or operations that depend on rapidly changing state.
20
21The hook returns a tuple containing:
22- The throttled state value
23- A throttled setter function that respects the configured wait time
24- The throttler instance for additional control
25
26For more direct control over throttling without state management,
27consider using the lower-level useThrottler hook instead.
28
29## State Management and Selector
30
31The hook uses TanStack Store for reactive state management via the underlying throttler instance.
32The `selector` parameter allows you to specify which throttler state changes will trigger a re-render,
33optimizing performance by preventing unnecessary re-renders when irrelevant state changes occur.
34
35**By default, there will be no reactive state subscriptions** and you must opt-in to state
36tracking by providing a selector function. This prevents unnecessary re-renders and gives you
37full control over when your component updates. Only when you provide a selector will the
38component re-render when the selected state values change.
39
40Available throttler state properties:
41- `executionCount`: Number of function executions that have been completed
42- `lastArgs`: The arguments from the most recent call to maybeExecute
43- `lastExecutionTime`: Timestamp of the last function execution in milliseconds
44- `nextExecutionTime`: Timestamp when the next execution can occur in milliseconds
45- `isPending`: Whether the throttler is waiting for the timeout to trigger execution
46- `status`: Current execution status ('disabled' | 'idle' | 'pending')
47
48## Type Parameters
49
50### TValue
51
52`TValue`
53
54### TSelected
55
56`TSelected` = `ThrottlerState`\<`Dispatch`\<`SetStateAction`\<`TValue`\>\>\>
57
58## Parameters
59
60### value
61
62`TValue`
63
64### options
65
66[`ReactThrottlerOptions`](../interfaces/ReactThrottlerOptions.md)\<`Dispatch`\<`SetStateAction`\<`TValue`\>\>, `TSelected`\>
67
68### selector?
69
70(`state`) => `TSelected`
71
72## Returns
73
74\[`TValue`, `Dispatch`\<`SetStateAction`\<`TValue`\>\>, [`ReactThrottler`](../interfaces/ReactThrottler.md)\<`Dispatch`\<`SetStateAction`\<`TValue`\>\>, `TSelected`\>\]
75
76## Example
77
78```tsx
79// Default behavior - no reactive state subscriptions
80const [value, setValue, throttler] = useThrottledState(0, { wait: 1000 });
81
82// Opt-in to re-render when execution count changes (optimized for tracking executions)
83const [value, setValue, throttler] = useThrottledState(
84 0,
85 { wait: 1000 },
86 (state) => ({ executionCount: state.executionCount })
87);
88
89// Opt-in to re-render when throttling state changes (optimized for loading indicators)
90const [value, setValue, throttler] = useThrottledState(
91 0,
92 { wait: 1000 },
93 (state) => ({
94 isPending: state.isPending,
95 status: state.status
96 })
97);
98
99// Opt-in to re-render when timing information changes (optimized for timing displays)
100const [value, setValue, throttler] = useThrottledState(
101 0,
102 { wait: 1000 },
103 (state) => ({
104 lastExecutionTime: state.lastExecutionTime,
105 nextExecutionTime: state.nextExecutionTime
106 })
107);
108
109// With custom leading/trailing behavior
110const [value, setValue] = useThrottledState(0, {
111 wait: 1000,
112 leading: true, // Update immediately on first change
113 trailing: false // Skip trailing edge updates
114});
115
116// Access throttler methods if needed
117const handleReset = () => {
118 setValue(0);
119 throttler.cancel(); // Cancel any pending updates
120};
121
122// Access the selected throttler state (will be empty object {} unless selector provided)
123const { executionCount, isPending } = throttler.state;
124```