React useRef Hook By Example: A Complete Guide

Linton Ye

Last Updated: 2021-03-07

useRef is a built-in React Hook. Perhaps you have used it to access DOM nodes (If not, don't worry. It's covered in this post).

But do you know it can do way more? It's a hidden gem 💎. Trust me, it can become a powerful tool in your arsenal.

This is a deep dive into useRef. With an example-driven approach, this article covers:

• What it is used for
• Its mental model
• Simple examples
• More practical examples
• Anti-patterns
• Related concepts
  • ref and useRef
  • useRef vs. useState
  • useRef vs. createRef

Along the way, we'll build a stopwatch and a like button (yes, exactly the same like button on this blog, feel free to steal the code):

What is useRef used for?

The useRef Hook in React can be used to directly access DOM nodes, as well as persist a mutable value across rerenders of a component.

Directly access DOM nodes

When combined with the ref attribute, we could use useRef to obtain the underlying DOM nodes to perform DOM operations imperatively. In fact, this is really an escape hatch. We should only do this sparsely for things that React doesn't provide a declarative API for, such as focus management. If we use it for everything (in theory we could), we'd lose the benefit of React's declarative programming paradigm.

Persist a mutable value across rerenders

This is what I'm going to focus on in this article.

Keep reading 👇.

The mental model of useRef

Here's the mental model that works for me:

useRef is like class instance variable for function components.

After a lot of struggle trying to understand useRef, I finally saw this single sentence. And it clicked! If you are hearing the same clicking sound in your mind right now already, feel free to skip to the examples section. Otherwise, if you are not familiar with JavaScript classes or class instance variables, read on. This section is for you.

The "rerendering time loop"

To understand how useRef works and why we need it, let's get started with a contrived (but useful) example. Can you build a counter without using the useState hook?

Let's give it a try:

function Counter() {
  let count = 0
  // console.log('render')
  return (
    <div className="flex flex-col justify-center items-center m-8">
      <div>{count}</div>
      <button
        className="bg-purple-700 px-6 text-white rounded-md hover:bg-purple-500"
        onClick={() => {
          console.log(count)
          count++
        }}
      >
        +1
      </button>
    </div>
  )
}

This doesn't work, even though the value of count increases on click. Why? React is oblivious to the change of local variables and, therefore, doesn't know when to update the DOM. We'd need to rerender the component, namely request React to call the component function Counter, to let the change reflected on the screen.

You can verify this by uncommenting the line console.log('render') right after let count = 0. The component isn't rendered when the user clicks the button.

OK. Then what if we force the component to render when count updates?

function Counter() {
  const forceRender = useForceRender()
  let count = 0
  return (
    <div className="flex flex-col justify-center items-center m-8">
      <div>{count}</div>
      <button
        className="bg-purple-700 px-6 text-white rounded-md hover:bg-purple-500"
        onClick={() => {
          console.log(count)
          count++
          forceRender()
        }}
      >
        +1
      </button>
    </div>
  )
}

This doesn't work either. The count displayed on the page stays zero. Even worse, the count value in the console stopped working too. It's always 0!

BTW, useForceRender above is a custom hook:

// I know, I broke my own rule of not using useState, but trust me, it's all for your good. :)
function useForceRender() {
  const setC = React.useState(0)[1]
  return () => setC((c) => c + 1)
}

Why? This is what I call rerendering time loop.

Every time when the component rerenders, it goes into a time loop. All the local variables in the function will be reset to their original values. That's why count is always 0.

That's no surprise, right? They are local variables defined in the function. When the function reruns, the variables are supposed to behave like that!

As straighforward as this sounds, sometimes it's easy to forget (I do it all the time). So remember, since a React component is rerendered all the time, all the local variables will go into a time loop, over and over again.

So, we need a solution that survives this "rerendering time loop". We want to preserve the value no matter how many times the component is rendered. If we update count to 42, at the next render it should still be 42, not the initial value 0.

Let's try the first approach: what if we move the variable out of the component function? It will no longer be affected by the rerendering time loop, right?

let count = 0
function Counter() {
  const forceRender = useForceRender()
  return (
    <div className="flex flex-col justify-center items-center m-8">
      <div>{count}</div>
      <button
        className="bg-purple-700 px-6 text-white rounded-md hover:bg-purple-500"
        onClick={() => {
          count++
          forceRender()
        }}
      >
        +1
      </button>
    </div>
  )
}

That's correct! It works! Yay!

Component instances

But wait a second, what if we want to have two counters?

function TwoCounters() {
  return (
    <div>
      Click both buttons a few times:
      <Counter />
      <Counter />
    </div>
  )
}
//
let count = 0;
function Counter() {
  const forceRender = useForceRender()
  return (
    <div className="flex flex-col justify-center items-center m-8">
      <div>{count}</div>
      <button
        className="bg-purple-700 px-6 text-white rounded-md hover:bg-purple-500"
        onClick={() => {
          count++
          forceRender()
        }}
      >
        +1
      </button>
    </div>
  )
}

So our counters are still broken. Did you try it in the preview window? The two counters are tied together. Clicking one button changes the other counter too!

That's because both counters are tied to the same variable count. What we need instead is to have a separate variable for each instance of the counter.

So the requirements are:

1. Persist a value across rerenders
2. Persist the value per component instance, throughout the full lifetime of that instance

Introducing useRef!

function TwoCounters() {
  return (
    <div>
      <Counter />
      <Counter />
    </div>
  )
}
//
function Counter() {
  const forceRender = useForceRender()
  /* 1. Get a "variable" that corresponds to the CURRENT INSTANCE of the component */
  let count = React.useRef(0)
  return (
    <div className="flex flex-col justify-center items-center m-8">
      {/* 2. Use the value stored inside the "variable" */}
      <div>{count.current}</div>
      <button
        className="bg-purple-700 px-6 text-white rounded-md hover:bg-purple-500"
        onClick={() => {
          /* 3. Update the value of the "variable" */
          count.current = count.current + 1
          forceRender()
        }}
      >
        +1
      </button>
    </div>
  )
}

But, but we are still using that useForceRender to update the DOM! If we comment out forceRender(), the counter stops working again! (try it)

What's the point of useRef if it relies on useState to work properly? Why don't we just use useState?

What's the point of useRef if it doesn't trigger a rerender when the value is updated?

In fact, being able to persist a value across rerenders without triggering another rerender is exactly why useRef is created. Sometimes we just don't want the component to rerender when the value is updated.

It's now time to look at a better example.

Example 1: previous value / state

Let's modify the Counter component. Now we want to display the previous value of the counter whenever the button is clicked. We can do so using a combination of useState, useEffect, and of course useRef.

function Counter() {
  const [count, setCount] = useState(0)
  const prevCount = useRef(0)
  useEffect(() => {
    // This runs every time AFTER Counter is rendered.
    prevCount.current = count
  })
  return (
    <div className="flex flex-col justify-center items-center m-8">
      <div>
        Prev: {prevCount.current}, Count: {count}
      </div>
      <button className="bg-purple-700 px-6 text-white rounded-md hover:bg-purple-500"
        onClick={() => setCount((c) => c + 1)}>+1</button>
    </div>
  )
}

Look, when saving the previous state in useEffect, we definitely don't want the component to rerender. Otherwise, it'd go into an infinite loop. So, useRef to the rescue!

Example 2: stopwatch (clear interval)

Now let's look at a more useful example. How about a stopwatch?

We can make the stopwatch tick with a combination of useState, useEffect and setInterval:

function StopWatch() {
  const [milliSeconds, setMilliSeconds] = useState(0);
  useEffect(() => {
    const interval = setInterval(() => {
      setMilliSeconds((ms) => ms + 1)
    }, 1);
    return () => clearInterval(interval);
  }, []);
  return ...
}

But how do we pause the stopwatch?

We can add another state ticking and clear the interval when ticking is false. Let's give it a try:

function StopWatch() {
  const [milliSeconds, setMilliSeconds] = useState(0);
  const [ticking, setTicking] = useState(false);
  useEffect(() => {
    if (ticking) {
      const interval = setInterval(() => {
        setMilliSeconds((ms) => ms + 1)
      }, 1);
      return () => clearInterval(interval);
    } else {
      // 🤔 "interval" isn't defined here
      clearInterval(interval)
    }
    // Remember to put "ticking" in the deps
  }, [ticking]);
  return ...
}

Did you see the problem? Where should we define that variable interval?

If we define interval in the outer scope, we'll taste the wrath of the rerendering time loop -- interval will always be undefined.

function StopWatch() {
  const [milliSeconds, setMilliSeconds] = useState(0);
  const [ticking, setTicking] = useState(false);
  let interval // ❌ interval will always be undefined here
  useEffect(() => {
    if (ticking) {
      interval = setInterval(() => {
        setMilliSeconds((ms) => ms + 1)
      }, 1);
      return () => clearInterval(interval);
    } else {
      clearInterval(interval)
    }
  }, []);
  return ...
}

We don't want to put it in state either, since it's really not something we would want to display on the UI. It's interval stuff.

Again, useRef to the rescue:

function StopWatch() {
  const [milliSeconds, setMilliSeconds] = useState(0)
  const [ticking, setTicking] = useState(false)
  // 1. Get the ref for the CURRENT INSTANCE of the component
  const interval = useRef()
  useEffect(() => {
    if (ticking) {
      // 2. Update the value via ".current"
      interval.current = setInterval(() => {
        setMilliSeconds((ms) => ms + 1)
      }, 1)
      return () => clearInterval(interval.current)
    } else {
      // 3. Access the value via ".current"
      interval.current && clearInterval(interval.current)
    }
  }, [ticking])
  return (
    <div className="App">
      <h1>{format(milliSeconds)}</h1>
      <button onClick={() => setTicking((c) => !c)}>
        {milliSeconds === 0 ? 'Start' : ticking ? 'Pause' : 'Resume'}
      </button>
    </div>
  )
}

Note: due to the way setInterval works in JavaScript, the stopwatch created with the code above is VERY inaccurate. You can check out a more accurate version in CodeSandbox here (but the usage of useRef is still the same).

Example 3: Press and hold to repeat

Let's check out the real thing! Just a reminder, this is what we want to build (remember to click and hold):

We are going to focus on the press-and-hold behavior:

1. When the mouse is down, wait a little bit;
2. If the mouse is still down after a threshold, say 500 milliseconds, start repeatedly increasing the like count at an interval until the mouse is up;

How would we implement this behavior?

In order to detect the press-and-hold gesture, we can use setTimeout. When the mouse is down, kick off the timeout. When the mouse is up, clear the timeout.

How do we set and clear the timeout when the component is rendered and rerendered, i.e. when the state mouseDown changes?

You already know the answer from Example 2, right? useRef!

function LikeButton(params) {
  const [mouseDown, setMouseDown] = useState(false)
  // 1. Create the ref that track the timeout
  const holdDetectionTimeoutRef = useRef()
  useEffect(() => {
    if (mouseDown) {
      // 2. Set the value of the ref
      holdDetectionTimeoutRef.current = setTimeout(() => {
        // TODO start increasing like count
      }, 500);
    } else {
      // 3. On a new render, clear the timeout with
      holdDetectionTimeoutRef.current &&
        clearTimeout(holdDetectionTimeoutRef.current);
    }
  }, [mouseDown])
  // set mouseDown in onMouseDown and onMouseUp
  return ...
}

Next, how do we repeatedly increase the like count? setInterval is what we need. And of course we'll use another ref to keep track of the interval reference across rerenders.

function LikeButton(params) {
  const [mouseDown, setMouseDown] = useState(false)
  const [likes, setLikes] = useState(0)
  const holdDetectionTimeoutRef = useRef()
  const intervalRef = useRef(0);
  useEffect(() => {
    if (mouseDown) {
      holdDetectionTimeoutRef.current = setTimeout(() => {
        // start increasing like count
        intervalRef.current = setInterval(() => {
          setLikes(l => l + 1)
        }, 100);
      }, 500);
      // Don't forget to clear both the timeout and interval
      // in the clean up function of "useEffect".
      return () => {
        holdDetectionTimeoutRef.current && clearTimeout(holdDetectionTimeoutRef.current)
        intervalRef.current && clearInterval(intervalRef.current)
      }
    } else {
      holdDetectionTimeoutRef.current &&
        clearTimeout(holdDetectionTimeoutRef.current);
      intervalRef.current && clearInterval(intervalRef.current);
    }
  }, [mouseDown])
  return ...
}

Finally, we can extract all the logic into a custom Hook usePressHoldRepeat:

function usePressHoldRepeat(
  callback,
  holdDetectionThreshold = 300,
  repeatDelay = 100,
) {
  const [mouseDown, setMouseDown] = useState(false)
  const intervalRef = useRef(0)
  const holdDetectionTimeoutRef = useRef(0)
  const runCallback = useCallback(
    () => typeof callback === 'function' && callback(),
    [callback],
  )
  useEffect(() => {
    if (mouseDown) {
      holdDetectionTimeoutRef.current = setTimeout(() => {
        intervalRef.current = setInterval(() => {
          runCallback()
        }, repeatDelay)
      }, holdDetectionThreshold)
      return () => {
        intervalRef.current && clearInterval(intervalRef.current)
        holdDetectionTimeoutRef.current &&
          clearTimeout(holdDetectionTimeoutRef.current)
      }
    } else {
      holdDetectionTimeoutRef.current &&
        clearTimeout(holdDetectionTimeoutRef.current)
      intervalRef.current && clearInterval(intervalRef.current)
    }
  }, [mouseDown, repeatDelay, runCallback, holdDetectionThreshold])
  return {
    onClick: runCallback,
    onMouseDown: (e) => {
      if (e.button === 0) setMouseDown(true)
    },
    onMouseUp: () => setMouseDown(false),
    onMouseOut: () => setMouseDown(false),
  }
}

When using the usePressHoldRepeat hook, remember to use useCallback to prevent excess renders due to the fact the function might be recreated on each render (time loop).

function LikeButton() {
  const [likes, setLikes] = useState(0);
  const addLike = useCallback(() => setLikes((c) => c + 1), []);
  const props = usePressHoldRepeat(addLike);
  return ...

Check out the full source code in this CodeSandbox

Note: The animation in this example is implemented with Framer Motion. If you want to learn how to make the best of it and avoid common pitfalls, check out this full course I made for you!

Anti-patterns

Assign to ref.current in render

Remember, updating a ref's value is a side effect. We should put it inside useEffect or event handlers. Don't update current at the top level of a function component.

function App() {
  let someRef = useRef()
  someRef.current = '❌ Updating a ref is a side effect!'
  useEffect(() => {
    someRef.current = "✅ This is OK"
  })
  const handleClick = () => {
    someRef.current = "✅ This is OK too"
  }
  return ...
}

Use ref.current in JSX and expect it to be reactive

We could use ref.current in JSX, as you've seen in Example 1. However, keep in mind that the value displayed might be stale since updating ref.current doesn't trigger a rerender. We need to trigger rerenders in other means, e.g. with useState.

Quiz & Related concepts

With the understanding of how useRef works, let's look at a few related concepts. I'm going to organize them as quiz questions since I think you'd be able to figure it out with the mental model built after reading this article this far.

Give it a try!

ref and useRef

As mentioned, we could use the ref attribute and useRef to obtain the access to underlying DOM nodes, like so:

function Editor() {
  /* 1. Call useRef */
  const textboxRef = useRef()
  return (
    <div>
      {/* 2. "Bind" the ref with the input */}
      <input type="text" ref={textboxRef} />
      <button
        onClick={() => {
          /* 3. Access the DOM node via ref.current */
          textboxRef.current.focus()
        }}
      >
        Focus
      </button>
    </div>
  )
}

But, have you wondered how it works?

// Somewhere in React code
ref.current = domNode

useRef vs. useState

What is the difference between useRef and useState? How do they relate to each other?

useRef vs. createRef

In React, there's another function called createRef:

const ref = React.createRef()

What is the difference between useRef and createRef? I know I didn't cover createRef so far in the article, but can you guess from its name?

Conclusion

There are two use cases of useRef:

1. Directly access DOM nodes to perform DOM operations imperatively
2. Persist a value across rerenders, throughout the full lifetime of a component instance

The second use is particularly powerful when combined with useEffect, useState and useCallback. In this post, we used it in two real-world scenarios:

1. Preserve previous state
2. Preserve the reference of a timeout or interval so that we can clear them at a later time (in another render round)

Do you have other examples of useRef in your projects? Let me know!

I hope you find this article useful!

One of my 2021 goals is to write more posts that are useful, interactive and entertaining. Want to receive early previews of future posts? Sign up below. No spam, unsubscribe anytime.

Subscribe

You may also like

React Mental Models: Cutting Holes In HTML

Updated: 2020-03-23

react

What is React to do with cutting holes on a cardboard? Surprisingly, they have a lot in common.

Read more

💪🐼👊

React Mental Models: Working With Input

Updated: 2020-03-31

react

How do we work with the HTML input in React? Its behavior might be surprising. Read this post to get a good understanding of Input. And you'll get to do some Kung Fu routines with Panda too.

Read more

React Mental Models: The True Face of JSX

Updated: 2020-04-20

react

What is an JSX tag really? It's JavaScript code in disguise. Let's reveal its true face!

Read more