debounce

Limit the frequency of a function call by delaying its execution until a certain amount of time has passed since the last invocation. It is commonly used in scenarios where you want to prevent a function from being called too frequently, such as handling user input or event listeners.

The debounced function comes with a cancel method to cancel delayed invocations and a flush method to immediately invoke them.

Provide an options object to indicate that func should be invoked on the leading and/or trailing edge of the wait timeout.

Subsequent calls to the debounced function return the result of the last func invocation.

Note

If leading and trailing options are true, func is invoked on the trailing edge of the timeout only if the the debounced function is invoked more than once during the wait timeout.

Demo

Frequency

LeadingTrailing

Trigger areaMove the mouse to start

Raw events over time

Debounced events

debounce function

function debounce<T extends AnyFunc>(func: T, timeout?: number): DebouncedFunc<T>

Creates a debounced function that delays invoking func until after wait milliseconds have elapsed since the last time the debounced function was invoked.

Type Parameters

• T extends AnyFunc

Parameters

• func: T The function to debounce.
• timeout?: number The number of milliseconds to delay.

Return DebouncedFunc<T>

---

function debounce<T extends AnyFunc>(func: T, options: DebounceOptions): DebouncedFunc<T>

Creates a debounced function that delays invoking func until after wait milliseconds have elapsed since the last time the debounced function was invoked.

Type Parameters

• T extends AnyFunc

Parameters

• func: T The function to debounce.
• options: DebounceOptions The options object.

Return DebouncedFunc<T>

---

function debounce<T extends AnyFunc>(func: T, options: DebounceOptions & { leading: true; }): DebouncedFuncLeading<T>

Creates a debounced function that delays invoking func until after wait milliseconds have elapsed since the last time the debounced function was invoked.

Type Parameters

• T extends AnyFunc

Parameters

• func: T The function to debounce.
• options: DebounceOptions & { leading: true; } The options object.

Return DebouncedFuncLeading<T>

DebounceOptions interface

interface DebounceOptions

Properties

Name	Type	Description
timeout	number	optional The number of milliseconds to delay.
maxWait	number	optional The maximum time func is allowed to be delayed before it’s invoked.
leading	boolean	optional Specify invoking on the leading edge of the timeout.
trailing	boolean	optional Specify invoking on the trailing edge of the timeout.

DebouncedFunc interface

interface DebouncedFunc<T extends AnyFunc>

Type Parameters

• T extends AnyFunc

Properties

Name	Type	Description
isPending	boolean	readonly Returns true if the debounced function is waiting to be invoked.

cancel method

cancel(): void

Throw away any pending invocation of the debounced function.

flush method

flush(): ReturnType<T> | undefined

If there is a pending invocation of the debounced function, invoke it immediately and return its return value.

Otherwise, return the value from the last invocation, or undefined if the debounced function was never invoked.

Return ReturnType<T> | undefined

DebouncedFuncLeading interface

interface DebouncedFuncLeading<T extends AnyFunc> extends DebouncedFunc<T>

Type Parameters

• T extends AnyFunc

Properties

Name	Type	Description
isPending	boolean	readonly Returns true if the debounced function is waiting to be invoked.

flush method

flush(): ReturnType<T>

If there is a pending invocation of the debounced function, invoke it immediately and return its return value.

Otherwise, return the value from the last invocation, or undefined if the debounced function was never invoked.

Return ReturnType<T>

cancel method

cancel(): void

Throw away any pending invocation of the debounced function.