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

useDebouncedValue.md

122 lines4.1 KB

1---
2id: useDebouncedValue
3title: useDebouncedValue
4---
5​
6```ts
7function useDebouncedValue<TValue, TSelected>(
8 value,
9 options,
10 selector?): [TValue, ReactDebouncer<Dispatch<SetStateAction<TValue>>, TSelected>];
11```
12​
13Defined in: [debouncer/useDebouncedValue.ts:87](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/debouncer/useDebouncedValue.ts#L87)
14​
15A React hook that creates a debounced value that updates only after a specified delay.
16Unlike useDebouncedState, this hook automatically tracks changes to the input value
17and updates the debounced value accordingly.
18​
19The debounced value will only update after the specified wait time has elapsed since
20the last change to the input value. If the input value changes again before the wait
21time expires, the timer resets and starts waiting again.
22​
23This is useful for deriving debounced values from props or state that change frequently,
24like search queries or form inputs, where you want to limit how often downstream effects
25or calculations occur.
26​
27The hook returns the current debounced value and the underlying debouncer instance.
28The debouncer instance can be used to access additional functionality like cancellation
29and execution counts.
30​
31## State Management and Selector
32​
33The hook uses TanStack Store for reactive state management via the underlying debouncer instance.
34The `selector` parameter allows you to specify which debouncer state changes will trigger a re-render,
35optimizing performance by preventing unnecessary re-renders when irrelevant state changes occur.
36​
37**By default, there will be no reactive state subscriptions** and you must opt-in to state
38tracking by providing a selector function. This prevents unnecessary re-renders and gives you
39full control over when your component updates. Only when you provide a selector will the
40component re-render when the selected state values change.
41​
42Available debouncer state properties:
43- `canLeadingExecute`: Whether the debouncer can execute on the leading edge
44- `executionCount`: Number of function executions that have been completed
45- `isPending`: Whether the debouncer is waiting for the timeout to trigger execution
46- `lastArgs`: The arguments from the most recent call to maybeExecute
47- `status`: Current execution status ('disabled' | 'idle' | 'pending')
48​
49## Type Parameters
50​
51### TValue
52​
53`TValue`
54​
55### TSelected
56​
57`TSelected` = `DebouncerState`\<`Dispatch`\<`SetStateAction`\<`TValue`\>\>\>
58​
59## Parameters
60​
61### value
62​
63`TValue`
64​
65### options
66​
67[`ReactDebouncerOptions`](../interfaces/ReactDebouncerOptions.md)\<`Dispatch`\<`SetStateAction`\<`TValue`\>\>, `TSelected`\>
68​
69### selector?
70​
71(`state`) => `TSelected`
72​
73## Returns
74​
75\[`TValue`, [`ReactDebouncer`](../interfaces/ReactDebouncer.md)\<`Dispatch`\<`SetStateAction`\<`TValue`\>\>, `TSelected`\>\]
76​
77## Example
78​
79```tsx
80// Default behavior - no reactive state subscriptions
81const [searchQuery, setSearchQuery] = useState('');
82const [debouncedQuery, debouncer] = useDebouncedValue(searchQuery, {
83 wait: 500 // Wait 500ms after last change
84});
85​
86// Opt-in to re-render when pending state changes (optimized for loading indicators)
87const [debouncedQuery, debouncer] = useDebouncedValue(
88 searchQuery,
89 { wait: 500 },
90 (state) => ({ isPending: state.isPending })
91);
92​
93// Opt-in to re-render when execution count changes (optimized for tracking executions)
94const [debouncedQuery, debouncer] = useDebouncedValue(
95 searchQuery,
96 { wait: 500 },
97 (state) => ({ executionCount: state.executionCount })
98);
99​
100// Opt-in to re-render when debouncing status changes (optimized for status display)
101const [debouncedQuery, debouncer] = useDebouncedValue(
102 searchQuery,
103 { wait: 500 },
104 (state) => ({
105 status: state.status,
106 canLeadingExecute: state.canLeadingExecute
107 })
108);
109​
110// debouncedQuery will update 500ms after searchQuery stops changing
111useEffect(() => {
112 fetchSearchResults(debouncedQuery);
113}, [debouncedQuery]);
114​
115// Handle input changes
116const handleChange = (e) => {
117 setSearchQuery(e.target.value);
118};
119​
120// Access the selected debouncer state (will be empty object {} unless selector provided)
121const { isPending, executionCount } = debouncer.state;
122```