tessl/npm-use-debounce

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

use-debounce

Name: tessl/npm-use-debounce
Author: tessl

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;
}

Workspace: tessl
Visibility: Public
Created: 7 months ago
Last updated: 3 months ago
Describes: pkg:npm/use-debounce@10.0.x
Publish Source: CLI
Badge