Gabe Ragland

Posted on Jan 17, 2019 • Updated on Dec 2, 2020

React Debounce Debouncing with React Hooks

#react #hooks #debounce #javascript

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.

Discussion (47)

JivkoJelev91 • Feb 24 '20 • Edited

Why not just:

export const debounce = (func, wait) => {
  let timeout;
  return function(...args) {
    const context = this;
    if (timeout) clearTimeout(timeout);
    timeout = setTimeout(() => {
      timeout = null;
      func.apply(context, args);
    }, wait);
  };
};

Now you can use this debouce in other hooks.

johanse7 • Apr 30 '20

how do you make the call debounce function ?

Dexter Marks-Barber • Jan 28

const onChange = debounce(event => setQuery(event?.target?.value))

rohan2734 • May 6 • Edited

nope not working , geting the state value as undefined

Dexter Marks-Barber • May 6

Are you able to show your code for the event handler and how you trigger the call?

rohan2734 • May 15

i have triggered the call in the same way, but it is not working at all ,and state is undefined

Michael Willian Santos • Mar 4 '20

My aproach is this way:

import { useMemo, useState } from 'react'

/**
 * Debounce a function by time
 * @param {Function} func
 * @param {Number} delay
 */

export default function useDebounce(func, delay) {
    const [id, setId] = useState(null)

    return useMemo(
        (...args) => {
            if (id) {
                clearTimeout(id)
            } else {
                setId(
                    setTimeout(() => {
                        setId(null)
                        func(...args)
                    }, delay)
                )
            }
        },
        [func]
    )
}

Gustavo • Nov 27 '20

This looks great! Could you give us an example on how to implement it?

George WL • Jan 25

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 ?? '');
  };

Guilherme Baron • Sep 23 '19

Great article!

I've been using this pattern with hooks lately:

const [value, setValue] = useState()
const debouncedValue = useDebounce(value, 800)

It's clean and works well for most of the cases.

Here's a version useDebounce implemented using lodash: github.com/gnbaron/use-lodash-debo...

Hein Haraldson Berg • Apr 21 '20 • Edited

Here’s my take on a lodash.debounce hook. I don’t see why the hook shouldn’t be more convenient to use, so I basically made a useState wrapper which updates the value immediately (a requirement for controlled inputs), and updates a signal, which is meant to be used in a useEffect’s dependency array, only whenever specified as per lodash.debounce’s docs.

Tom Belton • Jul 25 '19 • Edited

Great - thanks! The example would be easier to read if you included all the imports and exports. Great job.

Gabe Ragland • Jul 25 '19

Good call! Just updated the post.

Tom Belton • Jul 25 '19

Awesome! :)

rohan2734 • May 6

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?

Nathan Foster • Jan 10 • Edited

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

}, [])

Rezuan Ahmed • Sep 14

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

Guillaume Bersac • Aug 2 '19

Why using useEffect for the api call? I don't see any issue with doing async api calls inside a component rendering function.

Gabe Ragland • Aug 4 '19

Any side effects should be wrapped in useEffect or within an event handler like onClick. Not sure what could go wrong by inlining it like that, but know it’s heavily discouraged by the React team.

Jamison Dance • Nov 18 '19

You wrap side effects in useEffect so they don't run on every render. You technically could make a request inside render without wrapping it in useEffect, but it'll happen on every single render, which is usually not what you want.

You typically only want side effects to run when things they care about change, like when some search text changes. That's exactly what useEffect does for you - it helps make sure the side effects only run when they need to.

Raúl Marín • Apr 13 '20

This reply is great, thanks!

Aaron Levin • Oct 31 '19

Hmm this doesn't seem to work if you add text after the initial query (i.e. 'wolverine' as the first full term to debounce, then appending it to become 'wolverine x-men'.. the 'x-men' part doesnt show up until the debouncing times out). I feel like this code is so short and simple I should be able to figure it out, but I can't seem to see why the UI lags so hard on the second set of characters.

Aaron Levin • Oct 31 '19

Aha, I take it back! Turns out I needed to pull my search input into its own component. Problem solved! (I think)

Matt Wright • Mar 8 '19

How could you modify this to make it a "leading" debounce?

Cezar Luiz • Feb 13 '19

Awesome! I had a similar project and this looked easier than I thought!

Eran Sakal • Feb 10 '20

Hi,
Thanks for the article. I'm curious about the chosen approch of providing a value to the custom hook that gets updates over time.

export default function useDebounce(value, delay) {

Here we listen to value changes in the custom hook with the inner useEffect and react to changes. Most of the hooks I'm familiar with treat the arguments they get as sort of initialization values that doesn't change overtime or even if changed are not monitored. For example useState, useReducer, useSelector, useMemo, useCallback, useRef are all hooks that doesn't react to changes of the initial values provided to the hook.

I know that your sample works and is valid implementation but I'm sure if it will not confuse developers who read the code. you could easily expose a second argument to update the value which will look very similar to useState

wdyt?

Yevhen Kozlov • Mar 10 '20

useCallback, useSelector, useMemo, useReducer are actually operating on most recent arguments each run.
It's only useState and useRef who purposely ignore any changes on sequential calls

Giancarlos Isasi • Apr 21 '19

Thanks for share!

Igor Krupin • Nov 27 '19 • Edited

Very helpful, thank you! Years ago I needed something like this and ended up using throttle feature of redux sagas. Not bad, but I try to avoid redux (gets a bit unreadable over time).

I'm writing a new app and needed an "auto-save" feature where a form is auto-saved every x seconds, provided any of the inputs were changed. I started doing my own thing (setTimeout, setInterval) and luckily stumbled on this post. Saved me time. Elegant and it works.

Throttling API calls from UI is a very important technique to learn, I wish Facebook would throw some sort of "autocomplete" or "lookup text field" example where they use your code.

Chris • Aug 21 '19

Great read!
Just as a side note: you don't have to import react to your use-debounce.js.
" import { useState, useEffect } from 'react';"is just fine

Mark Gilligan • Jan 16

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

Thanks!

Yaron Levi • Sep 5 '20

Thanks! Helped me a lot

Alain D'Ettorre • Jul 22 '20

You've got a missing = here

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

Uladzimir Kasacheuski • Oct 2 '19 • Edited

This is really elegant! Have you thought about publishing this as a node_module?

Yevhen Kozlov • Mar 10 '20

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.

Mez Charney • Nov 18 '20

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

shakil ahmed • Aug 4 '19

Great work, thanks a lot. I want to write a similar post in my native language Bangla, is this ok if i use your post as reference and also your demo project to show how this work ?

Gabe Ragland • Aug 4 '19

Yeah sure! Please just link to my post as well somewhere.

shakil ahmed • Aug 5 '19

Thank you so much, i will.

Alex Dorosin • Apr 29 '20

thank you, kind sir!

Ruslan Baigunussov • Dec 17 '19

Try to hold down any key and you will see, that searching appears 2 times - after 500 ms after the first character and after 500 ms after the last. How to avoid this glitch?