Referencing values with refs

A click count the screen doesn't need

A shop wants to know how often people press Add to cart, to send the number to its analytics later. The number never appears on the page. So far, the only way you've had to make a component remember something between renders is state, and every state change makes React render again. Here is another way. Click the button three times, then look at the console under the result.

1import { useRef } from "react";2 3export default function App() {4  const clicks = useRef(0);5 6  function handleClick() {7    clicks.current = clicks.current + 1;8    console.log(`Add to cart was clicked ${clicks.current} times`);9  }10 11  return <button onClick={handleClick}>Add to cart</button>;12}

Line 4 asks React for a ref: useRef(0) returns an object with one property, current, which starts at 0. Line 7 adds one to clicks.current, and line 8 prints it. The console shows Add to cart was clicked 1 times, then 2, then 3: the ref remembered the count from click to click. The button never changed, and React never rendered App again, because nothing asked it to.

useRef: one object that lasts between renders

useRef is a hook, like useState: import it from react and call it at the top of your component. It takes the starting value and returns a plain JavaScript object with one property, current. On the first render, React makes that object. On every later render, React returns the very same object, and ignores the starting value you pass.

Always pass a starting value, even when you have none yet: then pass null, as the tea timer below does. In TypeScript, React 19's types require it, and useRef() with nothing in the brackets is an error, Expected 1 arguments, but got 0. Older code sometimes left it out.

Two things make a ref different from state. Changing it doesn't render, as you just saw. And it changes right away. State is a snapshot: inside one render, it keeps the value that render started with. Click this button once and read the console:

1import { useRef, useState } from "react";2 3export default function App() {4  const [quantity, setQuantity] = useState(1);5  const latest = useRef(1);6 7  function handleClick() {8    setQuantity(quantity + 1);9    latest.current = latest.current + 1;10    console.log("quantity:", quantity, "latest.current:", latest.current);11  }12 13  return <button onClick={handleClick}>Tea × {quantity}</button>;14}

Line 8 asks React to make quantity 2 in the next render. Line 9 makes latest.current 2 right now. Line 10 prints quantity: 1 latest.current: 2: this render's quantity is still 1, but the ref already holds 2. The button shows Tea × 2 after the new render. Click again and the console says quantity: 2 latest.current: 3.

You could build useRef from useState. Here is a small model, written for this lesson, not React's real code:

import { useState } from "react";

function useRef(initialValue) {
  const [ref] = useState({ current: initialValue });
  return ref;
}

Line 4 keeps an object in state and never calls the setter, so React never renders because of it, and returns the same object every time. Changing ref.current changes a property of that object, which React doesn't watch. (React has its own useRef, without the extra setter, but it behaves like this.)

Changing a ref doesn't render again

What if you show a ref on the screen? Here are two click counters, one in state and one in a ref. The ref button reads refClicks.current while rendering, on purpose, to show what goes wrong. Line 6 prints Render each time React calls App. In development, StrictMode calls it twice for each render, so the console shows each Render with a 2 beside it.

1import { useRef, useState } from "react";2 3export default function App() {4  const [stateClicks, setStateClicks] = useState(0);5  const refClicks = useRef(0);6  console.log("Render");7 8  return (9    <>10      <button onClick={() => setStateClicks(stateClicks + 1)}>State: {stateClicks}</button>{" "}11      <button onClick={() => (refClicks.current = refClicks.current + 1)}>Ref: {refClicks.current}</button>12    </>13  );14}

Click Ref: 0 three times. The button keeps saying Ref: 0, and no new Render appears: line 11 changed refClicks.current to 3, but nothing asked React to render. Now click State: 0. The setter on line 10 makes React render App again, and this render reads both values: the buttons say State: 1 and Ref: 3. The ref had all three clicks; the screen was behind.

Try it with the counters side by side. Each one counts the renders React commits. Click Ref a few times, then press Render the ref counter again.

The state side adds one render for every click. The ref side stays at 1 render however often you click, while refClicks.current counts up below it. When you make it render again, it reads the ref and catches up. That's why a value the screen shows belongs in state.

Refs and state side by side

Refs and state both remember a value between renders, and both belong to one use of a component on the page. The difference is what happens when the value changes. How to read the table: each row asks one question, with the answer for a ref and for state.

The rule of thumb: if the screen shows it, use state. If only your event handlers need it, like a timer's id or a count you send somewhere, a ref is enough, and it saves a render.

A stopwatch: the time in state, the timer in a ref

A tea timer needs both. The time it shows has to be state, so the screen updates. To stop it, the code needs the id that setInterval returns, and the screen never shows that id. Press Start, wait, then Stop.

1import { useRef, useState } from "react";2 3export default function App() {4  const [startTime, setStartTime] = useState(null);5  const [now, setNow] = useState(null);6  const intervalRef = useRef(null);7 8  function handleStart() {9    setStartTime(Date.now());10    setNow(Date.now());11    clearInterval(intervalRef.current);12    intervalRef.current = setInterval(() => {13      setNow(Date.now());14    }, 100);15  }16 17  function handleStop() {18    clearInterval(intervalRef.current);19  }20 21  let seconds = 0;22  if (startTime !== null && now !== null) {23    seconds = (now - startTime) / 1000;24  }25 26  return (27    <>28      <h2>Tea steeping: {seconds.toFixed(1)} s</h2>29      <button onClick={handleStart}>Start</button> <button onClick={handleStop}>Stop</button>30    </>31  );32}

1. Lines 4 and 5 keep the start time and the time now in state, as numbers of milliseconds from Date.now(). Line 6 keeps the interval id in a ref, starting as null.
2. handleStart sets both times on lines 9 and 10. Line 11 stops an interval that's already running, so pressing Start twice doesn't leave two of them. Lines 12 to 14 start a new interval that sets now every 100 milliseconds, and keep its id in intervalRef.current.
3. handleStop on line 18 reads the id and stops the interval.
4. Lines 21 to 24 work out the seconds during rendering, from state only, and line 28 shows them.

Why not a plain variable? Here is the same timer with let intervalId = null; on line 6 instead of the ref. Press Start, then Stop:

1import { useState } from "react";2 3export default function App() {4  const [startTime, setStartTime] = useState(null);5  const [now, setNow] = useState(null);6  let intervalId = null;7 8  function handleStart() {9    setStartTime(Date.now());10    setNow(Date.now());11    clearInterval(intervalId);12    intervalId = setInterval(() => {13      setNow(Date.now());14    }, 100);15  }16 17  function handleStop() {18    clearInterval(intervalId);19  }20 21  let seconds = 0;22  if (startTime !== null && now !== null) {23    seconds = (now - startTime) / 1000;24  }25 26  return (27    <>28      <h2>Tea steeping: {seconds.toFixed(1)} s</h2>29      <button onClick={handleStart}>Start</button> <button onClick={handleStop}>Stop</button>30    </>31  );32}

It keeps counting. Every render calls App again, and each call runs line 6 again and makes a new intervalId, set to null. handleStart stored the id in the variable of the render it belonged to. But its setStartTime made React render again at once, and that render made new functions with their own intervalId, so the handleStop you press reads null and stops nothing. (Each function sees the variables of the call that made it: closures.) Press Run again to stop it. State would work, but setting the id would render for nothing. A ref keeps one value across all the renders, and changing it costs nothing.

Keep refs out of rendering

Rendering should be pure: the same props, state, and context give the same JSX, and calling the component has no other effect. React relies on it. In development, StrictMode calls your component twice for each render to catch mistakes, and React can start a render and throw it away. A ref read or written while rendering breaks this. Here is a render counter written that way, a mistake on purpose:

1import { useRef, useState } from "react";2 3export default function App() {4  const [quantity, setQuantity] = useState(1);5  const renders = useRef(0);6  renders.current = renders.current + 1;7 8  return (9    <>10      <button onClick={() => setQuantity(quantity + 1)}>Tea × {quantity}</button>11      <p>Renders: {renders.current}</p>12    </>13  );14}

It says Renders: 2 before you click anything, and each click adds 2. Line 6 runs every time React calls the component, and StrictMode calls it twice, both times with the same ref. So the number counts calls, not renders, and in a production build it would count differently. Reading ref.current in JSX, as line 11 does, has the other problem you saw: the screen only shows it when something else renders.

The rule: read and write refs in event handlers and effects, never while rendering.

function App() {
  const intervalRef = useRef(null);

  // Not here: this runs while React renders.
  // intervalRef.current = 123;
  // return <p>{intervalRef.current}</p>;

  function handleStop() {
    // Here: event handlers run after a click, not while rendering.
    clearInterval(intervalRef.current);
  }
  // Effects are fine too; they run after React has updated the screen.
}

Lines 4 to 6 are what not to do: they run while React renders. Line 10 is inside an event handler, which runs after a click, so it's fine. Effects, covered in Synchronizing with effects, run after React updates the screen, so they may use refs too.

There is one exception: filling a ref the first time. useRef(createTracker("tea-page")) calls createTracker on every render, though React keeps only the first result. Click this button twice and count the Tracker created lines in the console:

1import { useRef, useState } from "react";2 3function createTracker(page) {4  console.log("Tracker created for", page);5  return {6    track(event) {7      console.log(page, event);8    },9  };10}11 12export default function App() {13  const [quantity, setQuantity] = useState(1);14  const tracker = useRef(createTracker("tea-page"));15 16  function handleClick() {17    setQuantity(quantity + 1);18    tracker.current.track("add one");19  }20 21  return <button onClick={handleClick}>Tea × {quantity}</button>;22}

Line 14 calls createTracker each time React calls App, and throws the new tracker away. Instead, start the ref empty and fill it once:

1import { useRef, useState } from "react";2 3function createTracker(page) {4  console.log("Tracker created for", page);5  return {6    track(event) {7      console.log(page, event);8    },9  };10}11 12export default function App() {13  const [quantity, setQuantity] = useState(1);14  const tracker = useRef(null);15  if (tracker.current === null) {16    tracker.current = createTracker("tea-page");17  }18 19  function handleClick() {20    setQuantity(quantity + 1);21    tracker.current.track("add one");22  }23 24  return <button onClick={handleClick}>Tea × {quantity}</button>;25}

Lines 15 to 17 read and write tracker.current while rendering, but only while it's still null. The console shows Tracker created for tea-page once, then tea-page add one for each click. The result is always the same, and it only happens on the first render, so the component stays predictable. This is called lazy initialization: making a value only when it's first needed.

An escape hatch: the latest message for a timer

React calls refs an escape hatch: a way to step outside its usual flow, where the screen is worked out from props and state. Use one when you need to hold something React doesn't draw: a timer's id, an object from another library, or, in the next lesson, a DOM element. Here is a chat that waits three seconds before it sends, so you can undo. Type a message, press Send, and keep typing before the three seconds are up.

1import { useRef, useState } from "react";2 3export default function App() {4  const [text, setText] = useState("");5  const [status, setStatus] = useState("");6  const timeoutRef = useRef(null);7  const latestText = useRef("");8 9  function handleChange(e) {10    setText(e.target.value);11    latestText.current = e.target.value;12  }13 14  function handleSend() {15    setStatus("Sending in 3 seconds…");16    clearTimeout(timeoutRef.current);17    timeoutRef.current = setTimeout(() => {18      setStatus(`Sent: "${latestText.current}"`);19    }, 3000);20  }21 22  function handleUndo() {23    clearTimeout(timeoutRef.current);24    setStatus("Not sent.");25  }26 27  return (28    <>29      <input value={text} onChange={handleChange} aria-label="Message" />{" "}30      <button onClick={handleSend}>Send</button> <button onClick={handleUndo}>Undo</button>31      <p>{status}</p>32    </>33  );34}

The status says what you had typed when the three seconds ran out, not when you pressed Send. Line 6 keeps the timeout's id, so handleUndo can cancel it on line 23. Line 7 keeps the latest text: line 11 updates it on every keystroke, next to the state on line 10. The timeout on line 18 reads latestText.current, the value now, not a snapshot.

Press Edit & run and change line 18 to read text instead of latestText.current. Now it sends what you had typed when you pressed Send: the timeout was made by that render, and it sees that render's text, as State as a snapshot explains. Neither is wrong; choose the one you mean. The ref is for when you mean "the newest value".

Common mix-ups

• "Changing ref.current updates the screen." No. React doesn't know it changed. The screen only shows the new value when something else makes the component render.
• "A ref is the same as a variable inside the component." No. A let inside the component starts over on every render. A ref keeps its value from render to render.
• "A ref is the same as a variable outside the component." No. A variable outside is shared by every use of the component on the page. Each use gets its own ref.
• "useRef(initialValue) resets the ref each render." No. React uses the starting value only on the first render and ignores it after that.
• "Refs are only for DOM elements." No. A ref can hold any value: a number, an id, an object. DOM elements are one common use, in the next lesson.
• "Use a ref to avoid renders and make the app faster." Only for values the screen doesn't show. Anything the screen shows must be state, or the screen falls behind.

Practice exercises

import { useRef } from "react";

export default function App() {
  const clicks = useRef(0);

  return (
    <button onClick={() => (clicks.current = clicks.current + 1)}>
      Clicked {clicks.current} times
    </button>
  );
}

1import { useRef } from "react";2 3export default function App() {4  const clicks = useRef(0);5 6  return (7    <button onClick={() => (clicks.current = clicks.current + 1)}>8      Clicked {clicks.current} times9    </button>10  );11}

import { useRef, useState } from "react";

export default function App() {
  const [count, setCount] = useState(0);
  const ref = useRef(0);

  function handleClick() {
    setCount(count + 1);
    ref.current = ref.current + 1;
    console.log(count, ref.current);
  }

  return <button onClick={handleClick}>Click me</button>;
}

1import { useRef, useState } from "react";2 3export default function App() {4  const [count, setCount] = useState(0);5  const ref = useRef(0);6 7  function handleClick() {8    setCount(count + 1);9    ref.current = ref.current + 1;10    console.log(count, ref.current);11  }12 13  return <button onClick={handleClick}>Click me</button>;14}

1import { useState } from "react";2 3export default function App() {4  const [message, setMessage] = useState("Kettle is off.");5  let timeoutId = null;6 7  function handleBoil() {8    setMessage("Boiling…");9    timeoutId = setTimeout(() => setMessage("Tea time!"), 3000);10  }11 12  function handleCancel() {13    clearTimeout(timeoutId);14    setMessage("Cancelled.");15  }16 17  return (18    <>19      <p>{message}</p>20      <button onClick={handleBoil}>Boil</button> <button onClick={handleCancel}>Cancel</button>21    </>22  );23}

1import { useRef, useState } from "react";2 3export default function App() {4  const [message, setMessage] = useState("Kettle is off.");5  const timeoutRef = useRef(null);6 7  function handleBoil() {8    setMessage("Boiling…");9    timeoutRef.current = setTimeout(() => setMessage("Tea time!"), 3000);10  }11 12  function handleCancel() {13    clearTimeout(timeoutRef.current);14    setMessage("Cancelled.");15  }16 17  return (18    <>19      <p>{message}</p>20      <button onClick={handleBoil}>Boil</button> <button onClick={handleCancel}>Cancel</button>21    </>22  );23}

1import { useRef } from "react";2 3export default function App() {4  const likes = useRef(12);5 6  function handleLike() {7    likes.current = likes.current + 1;8  }9 10  return (11    <>12      <p>{likes.current} likes</p>13      <button onClick={handleLike}>Like</button>14    </>15  );16}

1import { useState } from "react";2 3export default function App() {4  const [likes, setLikes] = useState(12);5 6  function handleLike() {7    setLikes(likes + 1);8  }9 10  return (11    <>12      <p>{likes} likes</p>13      <button onClick={handleLike}>Like</button>14    </>15  );16}

1import { useRef, useState } from "react";2 3function createTracker(page) {4  console.log("Tracker created for", page);5  return {6    track(event) {7      console.log(page, event);8    },9  };10}11 12export default function App() {13  const [quantity, setQuantity] = useState(1);14  const tracker = useRef(createTracker("tea-page"));15 16  function handleClick() {17    setQuantity(quantity + 1);18    tracker.current.track("add one");19  }20 21  return <button onClick={handleClick}>Tea × {quantity}</button>;22}

1import { useRef, useState } from "react";2 3function createTracker(page) {4  console.log("Tracker created for", page);5  return {6    track(event) {7      console.log(page, event);8    },9  };10}11 12export default function App() {13  const [quantity, setQuantity] = useState(1);14  const tracker = useRef(null);15  if (tracker.current === null) {16    tracker.current = createTracker("tea-page");17  }18 19  function handleClick() {20    setQuantity(quantity + 1);21    tracker.current.track("add one");22  }23 24  return <button onClick={handleClick}>Tea × {quantity}</button>;25}

1import { useState } from "react";2 3export default function App() {4  const [payments, setPayments] = useState(0);5 6  function handlePay() {7    setPayments(payments + 1);8  }9 10  return (11    <>12      <button onClick={handlePay}>Pay $4</button>13      <p>Payments sent: {payments}</p>14    </>15  );16}

1import { useRef, useState } from "react";2 3export default function App() {4  const [payments, setPayments] = useState(0);5  const lastPay = useRef(0);6 7  function handlePay() {8    const now = Date.now();9    if (now - lastPay.current < 1000) return;10    lastPay.current = now;11    setPayments(payments + 1);12  }13 14  return (15    <>16      <button onClick={handlePay}>Pay $4</button>17      <p>Payments sent: {payments}</p>18    </>19  );20}

Check your understanding

Key takeaways

• useRef(initialValue) returns { current: initialValue }, the same object on every render.
• Changing ref.current doesn't render again, and the new value is there at once.
• If the screen shows a value, it's state. If only your handlers need it, a ref is enough.
• Keep timer ids in refs: a plain variable starts over on every render.
• Read and write refs in event handlers and effects, not while rendering, except to fill an empty ref once.
• Refs are an escape hatch for things React doesn't draw: ids, outside objects, the latest value, and DOM elements.

Coming next: Manipulating the DOM with refs. It puts a DOM element in a ref, to focus a box or scroll to an item.