Open History to see the last commit
1---
2id: useDebouncedState
3title: useDebouncedState
4---
5
6```ts
7function useDebouncedState<TValue, TSelected>(
8 value,
9 options,
10 selector?): [TValue, Dispatch<StateUpdater<TValue>>, PreactDebouncer<Dispatch<StateUpdater<TValue>>, TSelected>];
11```
12
13Defined in: [debouncer/useDebouncedState.ts:79](https://github.com/TanStack/pacer/blob/main/packages/preact-pacer/src/debouncer/useDebouncedState.ts#L79)
14
15A Preact hook that creates a debounced state value, combining Preact's useState with debouncing functionality.
16This hook provides both the current debounced value and methods to update it.
17
18The state value is only updated after the specified wait time has elapsed since the last update attempt.
19If another update is attempted before the wait time expires, the timer resets and starts waiting again.
20This is useful for handling frequent state updates that should be throttled, like search input values
21or window resize dimensions.
22
23The hook returns a tuple containing:
24- The current debounced value
25- A function to update the debounced value
26- The debouncer instance with additional control methods
27
28## State Management and Selector
29
30The hook uses TanStack Store for reactive state management via the underlying debouncer instance.
31The `selector` parameter allows you to specify which debouncer 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 debouncer state properties:
40- `canLeadingExecute`: Whether the debouncer can execute on the leading edge
41- `executionCount`: Number of function executions that have been completed
42- `isPending`: Whether the debouncer is waiting for the timeout to trigger execution
43- `lastArgs`: The arguments from the most recent call to maybeExecute
44- `status`: Current execution status ('disabled' | 'idle' | 'pending')
45
46## Type Parameters
47
48### TValue
49
50`TValue`
51
52### TSelected
53
54`TSelected` = `DebouncerState`\<`Dispatch`\<`StateUpdater`\<`TValue`\>\>\>
55
56## Parameters
57
58### value
59
60`TValue`
61
62### options
63
64[`PreactDebouncerOptions`](../interfaces/PreactDebouncerOptions.md)\<`Dispatch`\<`StateUpdater`\<`TValue`\>\>, `TSelected`\>
65
66### selector?
67
68(`state`) => `TSelected`
69
70## Returns
71
72\[`TValue`, `Dispatch`\<`StateUpdater`\<`TValue`\>\>, [`PreactDebouncer`](../interfaces/PreactDebouncer.md)\<`Dispatch`\<`StateUpdater`\<`TValue`\>\>, `TSelected`\>\]
73
74## Example
75
76```tsx
77// Default behavior - no reactive state subscriptions
78const [searchTerm, setSearchTerm, debouncer] = useDebouncedState('', {
79 wait: 500 // Wait 500ms after last keystroke
80});
81
82// Opt-in to re-render when pending state changes (optimized for loading indicators)
83const [searchTerm, setSearchTerm, debouncer] = useDebouncedState(
84 '',
85 { wait: 500 },
86 (state) => ({ isPending: state.isPending })
87);
88
89// Opt-in to re-render when execution count changes (optimized for tracking executions)
90const [searchTerm, setSearchTerm, debouncer] = useDebouncedState(
91 '',
92 { wait: 500 },
93 (state) => ({ executionCount: state.executionCount })
94);
95
96// Opt-in to re-render when debouncing status changes (optimized for status display)
97const [searchTerm, setSearchTerm, debouncer] = useDebouncedState(
98 '',
99 { wait: 500 },
100 (state) => ({
101 status: state.status,
102 canLeadingExecute: state.canLeadingExecute
103 })
104);
105
106// Update value - will be debounced
107const handleChange = (e) => {
108 setSearchTerm(e.target.value);
109};
110
111// Access the selected debouncer state (will be empty object {} unless selector provided)
112const { isPending, executionCount } = debouncer.state;
113```