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

useThrottledValue.md

117 lines4.0 KB

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