React Debounce Debouncing with React Hooks

Today I'm going to show you how to build a useDebounce React Hook that makes it super easy to debounce API calls to ensure that they don't execute too frequently. I've also put together a demo that uses our hook. It searches the Marvel Comic API and uses useDebounce to prevent API calls from being fired on every keystroke.

Pretty nifty huh? Okay, now on to the code!

First let's figure out how we want our hook to be used and we can let that guide or actual implementation of the hook logic. Rather than debounce the calling of our API request we're going to design this hook to debounce any value within our component's render function. We're then going to combine this with useEffect to fire off a new API request whenever that input value changes. This code example assumes some familiarity with the useState and useEffect hooks, which you can learn about in the React Hook docs.

import React, { useState, useEffect } from 'react';
import useDebounce from './use-debounce';

// Usage
function App() {
  // State and setter for search term
  const [searchTerm, setSearchTerm] = useState('');
  // State and setter for search results
  const [results, setResults] = useState([]);
  // State for search status (whether there is a pending API request)
  const [isSearching, setIsSearching] = useState(false);

  // Now we call our hook, passing in the current searchTerm value.
  // The hook will only return the latest value (what we passed in) ...
  // ... if it's been more than 500ms since it was last called.
  // Otherwise, it will return the previous value of searchTerm.
  // The goal is to only have the API call fire when user stops typing ...
  // ... so that we aren't hitting our API rapidly.
  const debouncedSearchTerm = useDebounce(searchTerm, 500);

  // Here's where the API call happens
  // We use useEffect since this is an asynchronous action
  useEffect(
    () => {
      // Make sure we have a value (user has entered something in input)
      if (debouncedSearchTerm) {
        // Set isSearching state
        setIsSearching(true);
        // Fire off our API call
        searchCharacters(debouncedSearchTerm).then(results => {
          // Set back to false since request finished
          setIsSearching(false);
          // Set results state
          setResults(results);
        });
      } else {
        setResults([]);
      }
    },
    // This is the useEffect input array
    // Our useEffect function will only execute if this value changes ...
    // ... and thanks to our hook it will only change if the original ...
    // value (searchTerm) hasn't changed for more than 500ms.
    [debouncedSearchTerm]
  );

  // Pretty standard UI with search input and results
  return (
    <div>
      <input
        placeholder="Search Marvel Comics"
        onChange={e => setSearchTerm(e.target.value)}
      />

      {isSearching && <div>Searching ...</div>}

      {results.map(result => (
        <div key={result.id}>
          <h4>{result.title}</h4>
          <img
            src={`${result.thumbnail.path}/portrait_incredible.${
              result.thumbnail.extension
            }`}
          />
        </div>
      ))}
    </div>
  );
}

// API search function
function searchCharacters(search) {
  const apiKey = 'f9dfb1e8d466d36c27850bedd2047687';
  const queryString `apikey=${apiKey}&titleStartsWith=${search}`;
  return fetch(
    `https://gateway.marvel.com/v1/public/comics?${queryString}`,
    {
      method: 'GET'
    }
  )
    .then(r => r.json())
    .then(r => r.data.results)
    .catch(error => {
      console.error(error);
      return [];
    });
}

Okay, so that looks pretty good! Now let's build the actual hook so that our app works.

import React, { useState, useEffect } from 'react';

// Our hook
export default function useDebounce(value, delay) {
  // State and setters for debounced value
  const [debouncedValue, setDebouncedValue] = useState(value);

  useEffect(
    () => {
      // Set debouncedValue to value (passed in) after the specified delay
      const handler = setTimeout(() => {
        setDebouncedValue(value);
      }, delay);

      // Return a cleanup function that will be called every time ...
      // ... useEffect is re-called. useEffect will only be re-called ...
      // ... if value changes (see the inputs array below). 
      // This is how we prevent debouncedValue from changing if value is ...
      // ... changed within the delay period. Timeout gets cleared and restarted.
      // To put it in context, if the user is typing within our app's ...
      // ... search box, we don't want the debouncedValue to update until ...
      // ... they've stopped typing for more than 500ms.
      return () => {
        clearTimeout(handler);
      };
    },
    // Only re-call effect if value changes
    // You could also add the "delay" var to inputs array if you ...
    // ... need to be able to change that dynamically.
    [value] 
  );

  return debouncedValue;
}

And there you have it! We now have a debounce hook that we can use to debounce any value right in the body of our component. Debounced values can then be included in useEffect's input array, instead of the non-debounced values, to limit the frequency of that effect being called.

Also check out my React codebase generator. It will give you a nice UI, auth, database, payments and more. Thousands of React devs use it to build and launch apps quickly.

Comments

[Ruchit Gandhi]

Loved the explanation. Thanks!
Although I would use useRef hook to set the timer variable to reduce the heap memory usage.

const useDebounce = (value, delay = 500) => {
  const [debouncedValue, setDebouncedValue] = useState();
  const timer = useRef(null);
  useEffect(() => {
    timer.current = setTimeout(() => {
      setDebouncedValue(value);
    }, delay);
    return () => clearTimeout(timer.current);
  }, [value, delay]);

  return debouncedValue;
};

[Rezuan Ahmed]

export default function useDebounce(func, delay) {
  const [timer, setTimer] = useState(null)
  return (...args) => {
    clearTimeout(timer)
    let _temp = setTimeout(() => {
      func(...args)
    }, delay)
    setTimer(_temp)
  }
}

import useDebounce from './customHooks/useDebounce'

export default function App() {
  const [val, setVal] = useState("")
  const handleSearch = useDebounce((e) => {
    // api call
  }, 100)

  return (
    <div>
      <input
        onChange={(e) => setVal(e.target.val)}
        onKeyDown={handleSearch} />
    </div>
  )
}

[rohan2734]

this is not working, i am getting redundant calls, the function calls are not getting cancelled

[rohan2734]

why dont we do this in the useEffect?

import React, { useState, useEffect } from "react";

const useDebounce = (data, delay) => {
  const [debouncedData, setDebouncedData] = useState(data);
 var timerID;
  useEffect(() => {

    if(timerID){
       clearTimeout(timerID)
    } 
    console.log("debounce executed");
     timerID = setTimeout(() => {
      setDebouncedData(data);
    }, delay);
   // return () => {
      //clearTimeout(timerID);
    //};
  }, [data.blogTitle, data.blogDescription]);

  return debouncedData;
};

export default useDebounce;

i tried this but the cleartimeout was not working, the timeout was not being cleared, i didnt understand the reason.

can anyone explain?

[George WL]

whilst I like the idea of this, I think the UI and the API call should be far more decoupled, so instead I've went for:

// in the useDebounce file
import { useEffect } from 'react';
/**
 * @description for use in functions with side-effects but no return value
 * @export useDebouncedFunction
 */
export default function useDebouncedFunction(handler, watchedValue, delay) {
  useEffect(() => {
    const timeoutHandler = setTimeout(() => {
      handler();
    }, delay);
    return () => {
      clearTimeout(timeoutHandler);
    };
  }, [watchedValue, delay]);
}

// in the search file
  const [searchQuery, setSearchQuery] = React.useState('');

  const fetchX = async () => {
    await getX()
      .then((updatedStock: IStockResponse) => {
        setX(updated.data?? []);
      })
      .catch(err => {
        console.error(err);
      });
  };
  useDebouncedFunction(fetchStockVehicles, searchQuery, 1000);
  const handleSearch = (value: string) => {
    setSearchQuery(value ?? '');
  };

[Mark Gilligan]

This was a great guide, had been struggling for a while with getting something like this to work.

Thanks!

[Nathan Foster]

This makes the most since:

import { useCallback, useRef } from 'react'
export default function useDebounce(func, delay = 400) {
let debounce = useRef(null)
return useCallback(
(...args) => {
const context = this
clearTimeout(debounce.current)
debounce.current = setTimeout(() => {
func.apply(context, args)
}, delay)
},
[func],
)
}

Usage:

const handleWindowResize = useDebounce(SetWindow)

useEffect(() => {
window.addEventListener('resize', handleResize)

handleResize()

return () => {
  window.removeEventListener('resize', handleResize)
}

}, [])

[Mez Charney]

This was incredibly helpful in figuring out how to debounce with my custom hook fetch. Thank you!

[Yaron Levi]

Thanks! Helped me a lot

[ParhamZare]

Thank you for sharing that, it's a very useful and simple way.

[Alain D'Ettorre]

You've got a missing = here

const queryString `apikey=${apiKey}&titleStartsWith=${search}`;

[Ricardo Garcia Izasiga]

Very nice code! :) very helpfull

[Darpan]

Very useful. I signed up only to thank you.

[Alex Dorosin]

thank you, kind sir!

[Yevhen Kozlov]

Amazing, did not think to have debouncedValue instead of debounced version of callback.
Probably we better cancel processing in main useEffect to avoid race conditions.