useDebounce

useDebounce

Debounces a fast-changing state value. The returned value will only reflect the latest value after the specified delay has passed without further updates.

Usage Examples

Basic (Minimum Parameters)

The simplest possible implementation to delay a rapidly changing string.

import { useState, useEffect } from 'react';
import { useDebounce } from 'react-hook-lab';

function BasicInput() {
  const [text, setText] = useState('');
  const debouncedText = useDebounce(text);

  useEffect(() => {
    // Only fires after user stops typing for 300ms
    console.log("Search for:", debouncedText);
  }, [debouncedText]);

  return <input value={text} onChange={e => setText(e.target.value)} />;
}

Common (Standard Usage)

Customizing the delay for an expensive operation, like filtering a large list locally.

import { useState, useMemo } from 'react';
import { useDebounce } from 'react-hook-lab';

function FilterableList({ items }) {
  const [filter, setFilter] = useState('');
  // Wait 500ms before updating the filtered list
  const debouncedFilter = useDebounce(filter, 500);

  const filteredItems = useMemo(() => {
    return items.filter(item => item.includes(debouncedFilter));
  }, [items, debouncedFilter]);

  return (
    <div>
      <input 
        placeholder="Filter heavy list..." 
        value={filter} 
        onChange={e => setFilter(e.target.value)} 
      />
      <ul>
        {filteredItems.map(i => <li key={i}>{i}</li>)}
      </ul>
    </div>
  );
}

Advanced (All Parameters)

An exhaustive example utilizing all options, including leading execution and initial values.

import { useState } from 'react';
import { useDebounce } from 'react-hook-lab';

function AdvancedDebounce() {
  const [coords, setCoords] = useState({ x: 0, y: 0 });
  
  const debouncedCoords = useDebounce(
    coords, 
    1000, 
    {
      initialValue: { x: 50, y: 50 }, // Start with this value
      leading: true // Update immediately on the very first render, then debounce subsequent updates
    }
  );

  return (
    <div 
      onMouseMove={e => setCoords({ x: e.clientX, y: e.clientY })} 
      style={{ height: '100vh', width: '100vw' }}
    >
      <p>Raw Mouse: {coords.x}, {coords.y}</p>
      <p>Debounced (1s): {debouncedCoords.x}, {debouncedCoords.y}</p>
    </div>
  );
}

API Reference

Parameters

• value (Required)
  • Type: T
  • Description: The fast-changing state value to debounce.
• delay
  • Type: number
  • Default: 300
  • Description: The delay in milliseconds. The value will only update after this amount of time has passed since the last change.
• options
  • Type: UseDebounceOptions<T>
  • Default: {}
  • Description: Configuration object.
    • initialValue: (T, default: value) The starting value before any debounce logic runs.
    • leading: (boolean, default: false) If true, the very first update will be applied immediately without waiting for the delay. Subsequent updates are debounced normally. String values will be automatically .trim()'ed internally before updating.

Return Object

Returns T:

• The debounced value, safely updated only after the specified delay.