or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

callback-debouncing.mdindex.mdthrottling.mdvalue-debouncing.md
tile.json

tessl/npm-use-debounce

React hooks library for debouncing and throttling functionality with small footprint and comprehensive control features

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/use-debounce@10.0.x

To install, run

npx @tessl/cli install tessl/npm-use-debounce@10.0.0

index.mddocs/

use-debounce

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.

Package Information

  • Package Name: use-debounce
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install use-debounce

Core Imports

import { useDebounce, useDebouncedCallback, useThrottledCallback } from 'use-debounce';
import type { CallOptions, Options, ControlFunctions, DebouncedState } from 'use-debounce';

For CommonJS:

const { useDebounce, useDebouncedCallback, useThrottledCallback } = require('use-debounce');

Basic Usage

import React, { useState } from 'react';
import { useDebounce, useDebouncedCallback } from 'use-debounce';

function SearchComponent() {
  const [text, setText] = useState('');
  const [debouncedText] = useDebounce(text, 500);
  
  // Debounced callback for API calls
  const debouncedSearch = useDebouncedCallback(
    (searchTerm: string) => {
      console.log('Searching for:', searchTerm);
      // Perform API call here
    },
    300
  );

  return (
    <div>
      <input
        value={text}
        onChange={(e) => {
          setText(e.target.value);
          debouncedSearch(e.target.value);
        }}
      />
      <p>Current: {text}</p>
      <p>Debounced: {debouncedText}</p>
    </div>
  );
}

Architecture

use-debounce is built around three core patterns:

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

Capabilities

Value Debouncing

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

function useDebounce<T>(
  value: T,
  delay: number,
  options?: {
    maxWait?: number;
    leading?: boolean;
    trailing?: boolean;
    equalityFn?: (left: T, right: T) => boolean;
  }
): [T, DebouncedState<(value: T) => void>];

Value Debouncing

Callback Debouncing

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

function useDebouncedCallback<T extends (...args: any) => ReturnType<T>>(
  func: T,
  wait?: number,
  options?: Options
): DebouncedState<T>;

Callback Debouncing

Throttling

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

function useThrottledCallback<T extends (...args: any) => ReturnType<T>>(
  func: T,
  wait: number,
  options?: CallOptions
): DebouncedState<T>;

Throttling

Core Types

interface CallOptions {
  /** Controls if the function should be invoked on the leading edge of the timeout */
  leading?: boolean;
  /** Controls if the function should be invoked on the trailing edge of the timeout */
  trailing?: boolean;
}

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

interface ControlFunctions<ReturnT> {
  /** Cancel pending function invocations */
  cancel: () => void;
  /** Immediately invoke pending function invocations */
  flush: () => ReturnT | undefined;
  /** Returns true if there are any pending function invocations */
  isPending: () => boolean;
}

interface DebouncedState<T extends (...args: any) => ReturnType<T>>
  extends ControlFunctions<ReturnType<T>> {
  (...args: Parameters<T>): ReturnType<T> | undefined;
}