Master debounce and throttle techniques for React. Learn when to use each, implementation patterns, real-world examples, and performance optimization.

# Debouncing & Throttling: Essential Performance Patterns

Every interactive React application handles rapid user interactions: typing in search boxes, resizing windows, scrolling through feeds, or moving the mouse. Without optimization, each interaction triggers expensive operations—API calls, DOM updates, complex calculations—degrading performance. Debouncing and throttling are two fundamental techniques that prevent excessive function calls by controlling how often a function executes. Mastering these patterns is essential for building responsive applications.

# The Problem: Excessive Function Calls

# Why Should You Care?

Consider a user typing in a search box connected to an API:

      
typescript

function SearchUsers() {
  const [query, setQuery] = useState('');

  const handleSearch = async (e: React.ChangeEvent<HTMLInputElement>) => {
    const value = e.currentTarget.value;
    setQuery(value);
    
    // API call on EVERY keystroke
    const results = await fetch(`/api/search?q=${value}`);
    // ... handle results
  };

  return <input onChange={handleSearch} placeholder="Search..." />;
}

The problem: Typing "react" makes 5 API calls (r, re, rea, reac, react). Most are wasted. Your server suffers, your user experiences lag, and bandwidth is consumed unnecessarily.

This is where debouncing and throttling intervene—they reduce excessive function executions while preserving the user experience.

# Understanding Debouncing

# What Is Debouncing?

Debouncing delays function execution until the user stops performing an action. The function only executes after a specified period of inactivity.

# Visual Representation

      
typescript

User typing: r--e--a--c--t--[pause of 300ms]
            |  |  |  |  |
Keystroke events (suppressed)
                        |
                    Function executes once (300ms after last keystroke)

# Real-World Analogy

Think of an elevator. When someone presses the "close doors" button, it doesn't close immediately. It waits a few seconds, and if no one else presses a button, it closes. If someone else presses a button within those 3 seconds, the timer resets.

# Basic Debounce Implementation

TypeScript Version

      
typescript

export function debounce<T extends (...args: any[]) => any>(
  func: T,
  delay: number
): (...args: Parameters<T>) => void {
  let timeoutId: NodeJS.Timeout | null = null;

  return function (...args: Parameters<T>) {
    // Clear previous timeout
    if (timeoutId) {
      clearTimeout(timeoutId);
    }

    // Set new timeout
    timeoutId = setTimeout(() => {
      func(...args);
    }, delay);
  };
}

// Usage
const debouncedSearch = debounce(async (query: string) => {
  const results = await fetch(`/api/search?q=${query}`);
  console.log('Results:', results);
}, 300);

// Call it multiple times
debouncedSearch('r');
debouncedSearch('re');
debouncedSearch('rea');
debouncedSearch('reac');
debouncedSearch('react');
// Only the last call executes after 300ms of inactivity

JavaScript Version

      
javascript

export function debounce(func, delay) {
  let timeoutId = null;

  return function (...args) {
    if (timeoutId) {
      clearTimeout(timeoutId);
    }

    timeoutId = setTimeout(() => {
      func(...args);
    }, delay);
  };
}

const debouncedSearch = debounce(async (query) => {
  const results = await fetch(`/api/search?q=${query}`);
  console.log('Results:', results);
}, 300);

debouncedSearch('r');
debouncedSearch('re');
debouncedSearch('rea');
debouncedSearch('react');

# Understanding Throttling

# What Is Throttling?

Throttling limits function execution to at most once every X milliseconds, regardless of how many times the event fires.

# Visual Representation

      
typescript

User typing: r--e--a--c--t--[pause]--[paste: javascript]
            |  |  |  |  |            |  |  |  |  |  |  |
            |                        |
      Function executes    Function executes (after 300ms)

# Real-World Analogy

Imagine a water faucet with a valve that lets water flow only once per second. No matter how quickly you turn the handle, water only flows once per second.

# Basic Throttle Implementation

TypeScript Version

      
typescript

export function throttle<T extends (...args: any[]) => any>(
  func: T,
  interval: number
): (...args: Parameters<T>) => void {
  let lastExecutedTime = 0;

  return function (...args: Parameters<T>) {
    const now = Date.now();

    if (now - lastExecutedTime >= interval) {
      lastExecutedTime = now;
      func(...args);
    }
  };
}

// Usage
const throttledScroll = throttle((event: Event) => {
  console.log('Scroll event', window.scrollY);
}, 1000);

window.addEventListener('scroll', throttledScroll);
// Executes at most once per second

JavaScript Version

      
javascript

export function throttle(func, interval) {
  let lastExecutedTime = 0;

  return function (...args) {
    const now = Date.now();

    if (now - lastExecutedTime >= interval) {
      lastExecutedTime = now;
      func(...args);
    }
  };
}

const throttledScroll = throttle((event) => {
  console.log('Scroll event', window.scrollY);
}, 1000);

window.addEventListener('scroll', throttledScroll);

# Debounce vs Throttle Comparison

# When to Use Debounce

Use debounce when you only care about the final result after a period of inactivity:

Search inputs: Execute API call after user stops typing
Auto-save: Save document after user finishes editing
Form validation: Validate after user stops filling fields
Window resize: Recalculate layout after user finishes resizing

# When to Use Throttle

Use throttle when you need regular updates at a consistent rate:

Scroll events: Track scroll position for infinite scroll
Mouse move: Update tooltip position as user moves cursor
Window resize: Recalculate dimensions regularly during resize
API rate limiting: Send requests at regular intervals

# Comparison Table

Aspect	Debounce	Throttle
Execution timing	After inactivity	At regular intervals
Use case	Final result after pause	Consistent updates
Function calls	Fewer (typically 1)	Moderate (regular rate)
Latency	Can be high	Predictable
Example	Search input (300ms)	Scroll event (100ms)

# Implementing Debounce

# Advanced Debounce with Cancel

Sometimes you need to cancel pending debounce operations:

TypeScript Version

      
typescript

interface DebouncedFunction<T extends (...args: any[]) => any> {
  (...args: Parameters<T>): void;
  cancel: () => void;
  flush: () => void;
}

export function debounce<T extends (...args: any[]) => any>(
  func: T,
  delay: number
): DebouncedFunction<T> {
  let timeoutId: NodeJS.Timeout | null = null;
  let lastArgs: Parameters<T> | null = null;

  const debounced = (...args: Parameters<T>) => {
    lastArgs = args;

    if (timeoutId) {
      clearTimeout(timeoutId);
    }

    timeoutId = setTimeout(() => {
      func(...lastArgs!);
      timeoutId = null;
      lastArgs = null;
    }, delay);
  };

  debounced.cancel = () => {
    if (timeoutId) {
      clearTimeout(timeoutId);
      timeoutId = null;
      lastArgs = null;
    }
  };

  debounced.flush = () => {
    if (timeoutId && lastArgs) {
      clearTimeout(timeoutId);
      func(...lastArgs);
      timeoutId = null;
      lastArgs = null;
    }
  };

  return debounced;
}

JavaScript Version

      
javascript

export function debounce(func, delay) {
  let timeoutId = null;
  let lastArgs = null;

  const debounced = (...args) => {
    lastArgs = args;

    if (timeoutId) {
      clearTimeout(timeoutId);
    }

    timeoutId = setTimeout(() => {
      func(...lastArgs);
      timeoutId = null;
      lastArgs = null;
    }, delay);
  };

  debounced.cancel = () => {
    if (timeoutId) {
      clearTimeout(timeoutId);
      timeoutId = null;
      lastArgs = null;
    }
  };

  debounced.flush = () => {
    if (timeoutId && lastArgs) {
      clearTimeout(timeoutId);
      func(...lastArgs);
      timeoutId = null;
      lastArgs = null;
    }
  };

  return debounced;
}

# Using Cancel and Flush

      
typescript

const debouncedSave = debounce(async (content: string) => {
  await fetch('/api/save', {
    method: 'POST',
    body: JSON.stringify({ content }),
  });
}, 1000);

// Cancel pending save
function handleDiscard() {
  debouncedSave.cancel();
}

// Force immediate save
function handleSaveNow() {
  debouncedSave.flush();
}

# Implementing Throttle

# Advanced Throttle with Trailing Edge

Execute once immediately, then once more at the end:

TypeScript Version

      
typescript

interface ThrottleOptions {
  leading?: boolean;  // Execute on first call
  trailing?: boolean; // Execute on last call after interval
}

export function throttle<T extends (...args: any[]) => any>(
  func: T,
  interval: number,
  options: ThrottleOptions = { leading: true, trailing: true }
): (...args: Parameters<T>) => void {
  let lastExecutedTime = 0;
  let timeoutId: NodeJS.Timeout | null = null;
  let lastArgs: Parameters<T> | null = null;

  return function (...args: Parameters<T>) {
    const now = Date.now();
    lastArgs = args;

    if (!lastExecutedTime && !options.leading) {
      lastExecutedTime = now;
    }

    const remaining = interval - (now - lastExecutedTime);

    if (remaining <= 0) {
      if (timeoutId) {
        clearTimeout(timeoutId);
        timeoutId = null;
      }
      lastExecutedTime = now;
      func(...args);
    } else if (!timeoutId && options.trailing) {
      timeoutId = setTimeout(() => {
        lastExecutedTime = options.leading ? Date.now() : 0;
        timeoutId = null;
        func(...lastArgs!);
      }, remaining);
    }
  };
}

JavaScript Version

      
javascript

export function throttle(
  func,
  interval,
  options = { leading: true, trailing: true }
) {
  let lastExecutedTime = 0;
  let timeoutId = null;
  let lastArgs = null;

  return function (...args) {
    const now = Date.now();
    lastArgs = args;

    if (!lastExecutedTime && !options.leading) {
      lastExecutedTime = now;
    }

    const remaining = interval - (now - lastExecutedTime);

    if (remaining <= 0) {
      if (timeoutId) {
        clearTimeout(timeoutId);
        timeoutId = null;
      }
      lastExecutedTime = now;
      func(...args);
    } else if (!timeoutId && options.trailing) {
      timeoutId = setTimeout(() => {
        lastExecutedTime = options.leading ? Date.now() : 0;
        timeoutId = null;
        func(...lastArgs);
      }, remaining);
    }
  };
}

# Using Libraries

# lodash

The popular lodash library provides battle-tested implementations:

      
bash

npm install lodash
npm install --save-dev @types/lodash

      
typescript

import { debounce, throttle } from 'lodash';

// Debounce: execute after 500ms of inactivity
const debouncedSearch = debounce(
  async (query: string) => {
    const results = await fetch(`/api/search?q=${query}`);
  },
  500
);

// Throttle: execute at most once per second
const throttledResize = throttle(
  () => console.log('Window resized'),
  1000
);

// Cancel debounce
debouncedSearch.cancel();

// Force execution
debouncedSearch.flush();

# use-debounce Hook

For React-specific debouncing, use the use-debounce library:

      
bash

npm install use-debounce

      
typescript

import { useDebouncedValue, useDebounceCallback } from 'use-debounce';

function SearchUsers() {
  const [query, setQuery] = useState('');
  
  // Debounced value updates after 500ms
  const [debouncedQuery] = useDebouncedValue(query, 500);

  // Or use callback for side effects
  const [debouncedCallback] = useDebounceCallback(
    async (value: string) => {
      const results = await fetch(`/api/search?q=${value}`);
    },
    500
  );

  useEffect(() => {
    // Fetch only when debounced query changes
    if (debouncedQuery) {
      debouncedCallback(debouncedQuery);
    }
  }, [debouncedQuery]);

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

# Real-World Examples

# Example 1: Search Input with Debounce

TypeScript Version

      
typescript

interface SearchResult {
  id: string;
  title: string;
}

function ProductSearch() {
  const [query, setQuery] = useState('');
  const [results, setResults] = useState<SearchResult[]>([]);
  const [loading, setLoading] = useState(false);

  const debouncedSearch = debounce(async (searchQuery: string) => {
    if (!searchQuery.trim()) {
      setResults([]);
      return;
    }

    setLoading(true);
    try {
      const response = await fetch(`/api/products?q=${searchQuery}`);
      const data = await response.json();
      setResults(data);
    } catch (error) {
      console.error('Search failed:', error);
    } finally {
      setLoading(false);
    }
  }, 300);

  const handleInputChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    setQuery(e.currentTarget.value);
    debouncedSearch(e.currentTarget.value);
  };

  return (
    <div className="search-container">
      <input
        type="text"
        value={query}
        onChange={handleInputChange}
        placeholder="Search products..."
        className="search-input"
      />
      {loading && <p>Searching...</p>}
      <ul className="results">
        {results.map((result) => (
          <li key={result.id}>{result.title}</li>
        ))}
      </ul>
    </div>
  );
}

JavaScript Version

      
javascript

function ProductSearch() {
  const [query, setQuery] = useState('');
  const [results, setResults] = useState([]);
  const [loading, setLoading] = useState(false);

  const debouncedSearch = debounce(async (searchQuery) => {
    if (!searchQuery.trim()) {
      setResults([]);
      return;
    }

    setLoading(true);
    try {
      const response = await fetch(`/api/products?q=${searchQuery}`);
      const data = await response.json();
      setResults(data);
    } catch (error) {
      console.error('Search failed:', error);
    } finally {
      setLoading(false);
    }
  }, 300);

  const handleInputChange = (e) => {
    setQuery(e.currentTarget.value);
    debouncedSearch(e.currentTarget.value);
  };

  return (
    <div className="search-container">
      <input
        type="text"
        value={query}
        onChange={handleInputChange}
        placeholder="Search products..."
      />
      {loading && <p>Searching...</p>}
      <ul className="results">
        {results.map((result) => (
          <li key={result.id}>{result.title}</li>
        ))}
      </ul>
    </div>
  );
}

# Example 2: Window Resize with Throttle

      
typescript

function ResponsiveLayout() {
  const [width, setWidth] = useState(window.innerWidth);

  const throttledResize = throttle(() => {
    setWidth(window.innerWidth);
  }, 200);

  useEffect(() => {
    window.addEventListener('resize', throttledResize);
    return () => window.removeEventListener('resize', throttledResize);
  }, []);

  const columns = width > 1200 ? 4 : width > 768 ? 2 : 1;

  return (
    <div className={`grid grid-cols-${columns}`}>
      {/* Layout content */}
    </div>
  );
}

# Example 3: Auto-Save with Debounce

      
typescript

function DocumentEditor() {
  const [content, setContent] = useState('');
  const [isSaving, setIsSaving] = useState(false);
  const [lastSaved, setLastSaved] = useState<Date | null>(null);

  const debouncedSave = debounce(async (text: string) => {
    setIsSaving(true);
    try {
      await fetch('/api/documents/save', {
        method: 'POST',
        body: JSON.stringify({ content: text }),
      });
      setLastSaved(new Date());
    } catch (error) {
      console.error('Save failed:', error);
    } finally {
      setIsSaving(false);
    }
  }, 1000);

  const handleContentChange = (e: React.ChangeEvent<HTMLTextAreaElement>) => {
    setContent(e.currentTarget.value);
    debouncedSave(e.currentTarget.value);
  };

  return (
    <div>
      <textarea
        value={content}
        onChange={handleContentChange}
        placeholder="Start typing..."
        className="editor"
      />
      {isSaving && <span className="saving">Saving...</span>}
      {lastSaved && (
        <p className="last-saved">
          Last saved: {lastSaved.toLocaleTimeString()}
        </p>
      )}
    </div>
  );
}

# React Hooks Integration

# Custom useDebounce Hook

Create a reusable hook for debounced values:

TypeScript Version

      
typescript

export function useDebounce<T>(value: T, delay: number): T {
  const [debouncedValue, setDebouncedValue] = useState(value);

  useEffect(() => {
    const timeoutId = setTimeout(() => {
      setDebouncedValue(value);
    }, delay);

    return () => clearTimeout(timeoutId);
  }, [value, delay]);

  return debouncedValue;
}

// Usage
function SearchWithHook() {
  const [query, setQuery] = useState('');
  const debouncedQuery = useDebounce(query, 300);

  useEffect(() => {
    if (debouncedQuery) {
      // Fetch results when debounced query changes
      console.log('Fetching results for:', debouncedQuery);
    }
  }, [debouncedQuery]);

  return (
    <input
      value={query}
      onChange={(e) => setQuery(e.currentTarget.value)}
      placeholder="Search..."
    />
  );
}

JavaScript Version

      
javascript

export function useDebounce(value, delay) {
  const [debouncedValue, setDebouncedValue] = useState(value);

  useEffect(() => {
    const timeoutId = setTimeout(() => {
      setDebouncedValue(value);
    }, delay);

    return () => clearTimeout(timeoutId);
  }, [value, delay]);

  return debouncedValue;
}

# Custom useThrottle Hook

      
typescript

export function useThrottle<T>(value: T, interval: number): T {
  const [throttledValue, setThrottledValue] = useState(value);
  const lastUpdatedRef = useRef(Date.now());

  useEffect(() => {
    const now = Date.now();

    if (now >= lastUpdatedRef.current + interval) {
      lastUpdatedRef.current = now;
      setThrottledValue(value);
    } else {
      const timeoutId = setTimeout(
        () => {
          lastUpdatedRef.current = Date.now();
          setThrottledValue(value);
        },
        interval - (now - lastUpdatedRef.current)
      );

      return () => clearTimeout(timeoutId);
    }
  }, [value, interval]);

  return throttledValue;
}

# Common Pitfalls

# Pitfall 1: Creating New Debounced Function Every Render

      
typescript

// ❌ WRONG: New debounced function every render
function SearchBox() {
  const handleSearch = (query: string) => {
    // API call
  };

  const debouncedSearch = debounce(handleSearch, 300); // New function!

  return <input onChange={(e) => debouncedSearch(e.currentTarget.value)} />;
}

// ✅ CORRECT: Create once and reuse
function SearchBox() {
  const debouncedSearch = useRef(
    debounce((query: string) => {
      // API call
    }, 300)
  ).current;

  return <input onChange={(e) => debouncedSearch(e.currentTarget.value)} />;
}

# Pitfall 2: Debouncing State Updates Instead of Effects

      
typescript

// ❌ WRONG: Debouncing the state setter
const debouncedSetQuery = debounce(setQuery, 300);

// ✅ CORRECT: Debounce the side effect
const debouncedSearch = debounce(fetchResults, 300);
useEffect(() => {
  debouncedSearch(query);
}, [query]);

# Pitfall 3: Not Cleaning Up Event Listeners

      
typescript

// ❌ WRONG: Event listener never removed
function Component() {
  const throttledScroll = throttle(() => {
    console.log('Scrolled');
  }, 1000);

  window.addEventListener('scroll', throttledScroll); // Memory leak!
}

// ✅ CORRECT: Clean up in useEffect
function Component() {
  useEffect(() => {
    const throttledScroll = throttle(() => {
      console.log('Scrolled');
    }, 1000);

    window.addEventListener('scroll', throttledScroll);
    return () => window.removeEventListener('scroll', throttledScroll);
  }, []);
}

# FAQ

Q: Should I debounce or throttle search inputs?

A: Debounce. Search inputs benefit from waiting for the user to finish typing. Throttling would still make requests while typing, defeating the purpose.

Q: What's the typical delay for debouncing?

A: 200-500ms for search and typing. 1000ms+ for auto-save. Start with 300ms and adjust based on your use case.

Q: Can I use both debounce and throttle together?

A: Yes, but rarely needed. Consider throttle with a small interval (100-300ms) for things like scroll handlers where you want both responsiveness and performance.

Q: Does debounce work with form submissions?

A: Not directly. You typically debounce the async operation (API call), not the form submission itself. Use debounce inside the submit handler.

Q: How do I cancel a pending debounced function?

A: Implement a cancel method that clears the timeout. The useCallback approach with refs works well for React components.

Q: What's the performance impact of debouncing?

A: Minimal. Debouncing reduces API calls, calculations, and DOM updates, improving overall performance significantly. The overhead of debouncing itself is negligible.

Q: Should I debounce useEffect dependencies?

A: No, debounce the side effect itself, not the dependency. Create a debounced function inside useEffect and call it when dependencies change.

Key Takeaway: Debounce for delayed execution after inactivity (search, auto-save), throttle for regular execution during rapid events (scroll, resize). Combine with React hooks for clean, reusable patterns. Always clean up event listeners to prevent memory leaks.

Questions? Where have you applied debouncing or throttling in your projects? Share your optimization strategies in the comments.