0
# use-debounce
1

2
use-debounce is a React hooks library that provides debouncing and throttling functionality with a small footprint (<1KB). It offers three main hooks for optimizing performance in React applications: `useDebounce` for value debouncing, `useDebouncedCallback` for callback function debouncing, and `useThrottledCallback` for throttling callbacks. The library is compatible with lodash/underscore debounce API and includes advanced features like leading/trailing execution, maxWait limits, and comprehensive control methods.
3

4
## Package Information
5

6
- **Package Name**: use-debounce
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install use-debounce`
10

11
## Core Imports
12

13
```typescript
14
import { useDebounce, useDebouncedCallback, useThrottledCallback } from 'use-debounce';
15
import type { CallOptions, Options, ControlFunctions, DebouncedState } from 'use-debounce';
16
```
17

18
For CommonJS:
19

20
```javascript
21
const { useDebounce, useDebouncedCallback, useThrottledCallback } = require('use-debounce');
22
```
23

24
## Basic Usage
25

26
```typescript
27
import React, { useState } from 'react';
28
import { useDebounce, useDebouncedCallback } from 'use-debounce';
29

30
function SearchComponent() {
31
  const [text, setText] = useState('');
32
  const [debouncedText] = useDebounce(text, 500);
33
  
34
  // Debounced callback for API calls
35
  const debouncedSearch = useDebouncedCallback(
36
    (searchTerm: string) => {
37
      console.log('Searching for:', searchTerm);
38
      // Perform API call here
39
    },
40
    300
41
  );
42

43
  return (
44
    <div>
45
      <input
46
        value={text}
47
        onChange={(e) => {
48
          setText(e.target.value);
49
          debouncedSearch(e.target.value);
50
        }}
51
      />
52
      <p>Current: {text}</p>
53
      <p>Debounced: {debouncedText}</p>
54
    </div>
55
  );
56
}
57
```
58

59
## Architecture
60

61
use-debounce is built around three core patterns:
62

63
- **Value Debouncing**: `useDebounce` delays state updates by debouncing the value itself, ideal for reducing re-renders from rapid state changes
64
- **Callback Debouncing**: `useDebouncedCallback` creates debounced versions of functions, perfect for handling events like API calls or expensive operations
65
- **Throttling**: `useThrottledCallback` limits function execution frequency, useful for high-frequency events like scrolling or resizing
66
- **Control Functions**: All hooks return control methods (`cancel`, `flush`, `isPending`) for fine-grained execution control
67
- **Server-Side Rendering**: Compatible with SSR environments with optional server-side debouncing
68

69
## Capabilities
70

71
### Value Debouncing
72

73
Debounces values to reduce component re-renders and optimize performance. Returns the debounced value and a set of control functions.
74

75
```typescript { .api }
76
function useDebounce<T>(
77
  value: T,
78
  delay: number,
79
  options?: {
80
    maxWait?: number;
81
    leading?: boolean;
82
    trailing?: boolean;
83
    equalityFn?: (left: T, right: T) => boolean;
84
  }
85
): [T, DebouncedState<(value: T) => void>];
86
```
87

88
[Value Debouncing](./value-debouncing.md)
89

90
### Callback Debouncing
91

92
Creates debounced versions of callback functions with comprehensive control options including leading/trailing execution and maxWait functionality.
93

94
```typescript { .api }
95
function useDebouncedCallback<T extends (...args: any) => ReturnType<T>>(
96
  func: T,
97
  wait?: number,
98
  options?: Options
99
): DebouncedState<T>;
100
```
101

102
[Callback Debouncing](./callback-debouncing.md)
103

104
### Throttling
105

106
Creates throttled versions of callback functions that execute at most once per specified interval, ideal for high-frequency events.
107

108
```typescript { .api }
109
function useThrottledCallback<T extends (...args: any) => ReturnType<T>>(
110
  func: T,
111
  wait: number,
112
  options?: CallOptions
113
): DebouncedState<T>;
114
```
115

116
[Throttling](./throttling.md)
117

118
## Core Types
119

120
```typescript { .api }
121
interface CallOptions {
122
  /** Controls if the function should be invoked on the leading edge of the timeout */
123
  leading?: boolean;
124
  /** Controls if the function should be invoked on the trailing edge of the timeout */
125
  trailing?: boolean;
126
}
127

128
interface Options extends CallOptions {
129
  /** The maximum time the given function is allowed to be delayed before it's invoked */
130
  maxWait?: number;
131
  /** If set to true, all debouncing and timers will happen on the server side as well */
132
  debounceOnServer?: boolean;
133
}
134

135
interface ControlFunctions<ReturnT> {
136
  /** Cancel pending function invocations */
137
  cancel: () => void;
138
  /** Immediately invoke pending function invocations */
139
  flush: () => ReturnT | undefined;
140
  /** Returns true if there are any pending function invocations */
141
  isPending: () => boolean;
142
}
143

144
interface DebouncedState<T extends (...args: any) => ReturnType<T>>
145
  extends ControlFunctions<ReturnType<T>> {
146
  (...args: Parameters<T>): ReturnType<T> | undefined;
147
}
148
```