## Introduction: Why Refs Matter React is built on a simple idea: you describe the UI as a function of state, and React updates the DOM when state changes. Most of the time you don't need to touch the DOM directly. But sometimes you do. You need to focus an input after a form error. You need to scroll a list to the newly added item. You need to measure an element's size or integrate a chart library that expects a DOM node. In those cases, React's declarative model doesn't give you a direct way to say "do this to that element." Refs are React's escape hatch: they let you hold a reference to a DOM node (or any mutable value) and use it in effects or event handlers without triggering re-renders. Without refs, you'd be forced to abuse state (e.g. storing the DOM node in state, which is an anti-pattern) or leave React's world entirely. With refs, you stay inside React while reaching through to the real DOM or to mutable identity when you need it. By the end of this guide you will: - Understand what a ref is and how it differs from state - Use `useRef` for DOM access and for holding mutable values - Know when to use refs vs state - Use callback refs when you need dynamic refs or cleanup - Forward refs through wrapper components with `forwardRef` - Expose custom imperative APIs with `useImperativeHandle` - Apply refs to real problems: focus, scroll, measurements, third-party libs - Avoid common pitfalls that cause bugs or confusion Examples in this guide use **TypeScript** so you can see how refs are typed in practice (e.g. `useRef(null)`, `forwardRef`). The concepts are the same in JavaScript; the types are there to make the API clear and to give you a reference for your own code. Let's start with the mental model. --- ## What Is a Ref? (Mental Model) A ref is a **mutable box that persists across renders**. You create it once, and React gives you the same object on every render. You can put anything in that box: a DOM node, a timer ID, a previous value, or any JavaScript value. Updating the contents of the box does **not** cause a re-render. ### The Box Metaphor Think of a ref as a box with a single slot: `.current`. You put something in the box; you can change what's in the box whenever you want. The box itself is stable—React doesn't replace it between renders. So when you do: ```ts const box = useRef(initialValue); ``` you get an object `{ current: initialValue }`. On the next render, you get the **same** object, still with whatever you last assigned to `box.current`. Changing `box.current` does not tell React to re-render. ### Refs vs State: The Key Difference | | State | Ref | |--|--------|-----| | Update triggers re-render? | Yes | No | | Value persists across renders? | Yes | Yes | | Updates should be synchronous? | No (batched) | Yes (immediate) | | Typical use | What the user sees | Identity, DOM node, mutable handle | When you need the screen to reflect a change (e.g. "show the modal," "increment the counter"), you use state. When you need to keep a reference to something without redrawing the UI (e.g. "this input element," "the last timer ID"), you use a ref. ### Why "Ref"? "Ref" is short for reference. You're holding a reference to something: usually a DOM node, or sometimes a mutable value that you want to persist without causing re-renders. React's refs are not special JavaScript—they're just objects with a `current` property. The special part is that React gives you the same object on every render and, when you assign a ref to a DOM element, React fills `.current` with that element. --- ## useRef: The Primary API In function components, refs are created with `useRef`. ### Signature ```ts const ref = useRef(initialValue); // In TypeScript you often specify the type: useRef(null) ``` - **Argument:** `initialValue` is the value of `ref.current` on the first render. It can be any type: `null`, a number, a DOM node, etc. It's only used for the initial render; if you pass `null`, that's common for DOM refs because the node isn't mounted yet. - **Returns:** A plain object `{ current: initialValue }`. The same object is returned on every render. ### Basic Examples **Holding a number (e.g. render count):** ```tsx function RenderCounter() { const countRef = useRef(0); countRef.current += 1; return

This component has rendered {countRef.current} times.

; } ``` Here we're not using state, so updating `countRef.current` doesn't cause a re-render. The displayed count only updates when something else (e.g. parent state) causes a re-render. So this is mainly useful for debugging or for reading "how many times have I rendered" in effects. **Holding a DOM node:** ```tsx function TextInput() { const inputRef = useRef(null); function focusInput() { inputRef.current?.focus(); } return ( <> ); } ``` When the `input` mounts, React sets `inputRef.current` to that DOM element. When it unmounts, React sets it back to `null`. So we use optional chaining (`?.`) when calling `focus()`. **Holding a previous value:** ```tsx function usePrevious(value: T): T | undefined { const ref = useRef(undefined); useEffect(() => { ref.current = value; }); return ref.current; } ``` On each render, `ref.current` still holds the previous run's value (because the effect runs after paint). So you return the "previous" value. This pattern is useful for comparing "previous prop vs current" in effects. ### Object Ref vs DOM Ref - **Object ref:** You create the ref and you're responsible for what you put in `.current`. Example: `useRef(0)` for a number, or `useRef(null)` and later assigning a timer ID. - **DOM ref:** You pass the ref to a React element with the `ref` prop: ``. React assigns the DOM node to `inputRef.current` when the element mounts and sets it to `null` when it unmounts. You use the same `useRef` for both; the difference is whether you assign `.current` yourself or let React do it via the `ref` prop. --- ## Refs vs State: When to Use Which Getting this wrong leads to unnecessary re-renders, bugs, or awkward code. Use this as a decision guide. ### Use State When: - The value must be **shown on the screen** (or drive what is shown). - Changing the value should **trigger a re-render** (e.g. form input, open/closed modal, list of items). - The value is **part of the declarative UI model** (what should the DOM look like?). Examples: text input value, modal open/closed, selected tab, list of todos. ### Use a Ref When: - You need a **reference to a DOM node** (to focus, scroll, measure, or pass to a third-party library). - You need to **store something that shouldn't trigger a re-render** (timer ID, previous value, subscription, instance of an imperative library). - You need **mutable identity** that persists across renders without affecting the tree. Examples: input element for focus, scroll container, interval ID, previous props for comparison. ### Decision Table | Need | Use | |------|-----| | Show/hide UI, update displayed value | State | | Focus an input, scroll to element | Ref (DOM) | | Store timer ID, subscription, previous value | Ref (object) | | Parent needs to call a method on a child (e.g. focus) | Ref + `forwardRef` / `useImperativeHandle` | | Store value that is both displayed and read in effects | State (and optionally ref for "previous" if needed) | ### Anti-Pattern: Storing DOM Nodes in State Don't do this: ```tsx const [inputElement, setInputElement] = useState(null); // ... ``` Putting a DOM node in state is wrong because: (1) React may re-render when you set it, (2) DOM nodes are mutable and not meant to be React state, and (3) refs exist for this. Use `useRef(null)` and `ref={inputRef}` instead. --- ## DOM Refs: Accessing Native Elements The most common use of refs is attaching to a native DOM element so you can call DOM APIs. ### Attaching a Ref to an Element Pass the ref to the `ref` prop of a **host** element (a real HTML element, not a custom component): ```tsx function SearchForm() { const inputRef = useRef(null); useEffect(() => { // After mount, inputRef.current is the DOM node inputRef.current?.focus(); }, []); return ( ); } ``` React will set `inputRef.current` to the DOM element when the input mounts and set it to `null` when it unmounts. So in effects or event handlers you can safely use `inputRef.current` (with optional chaining if the component might have unmounted). ### What You Can Do With a DOM Ref Once you have the element, you can use any DOM API on it: **Focus:** ```ts inputRef.current?.focus(); inputRef.current?.blur(); ``` **Scroll:** ```ts divRef.current?.scrollIntoView({ behavior: 'smooth' }); listRef.current?.scrollTo(0, listRef.current.scrollHeight); ``` **Measurements:** ```ts const rect = divRef.current?.getBoundingClientRect(); const width = divRef.current?.offsetWidth; const height = divRef.current?.offsetHeight; ``` **Content:** ```ts const text = inputRef.current?.value; textareaRef.current?.value = 'New text'; ``` **Events (use sparingly; prefer React's synthetic events when possible):** ```ts divRef.current?.addEventListener('scroll', handleScroll); // Cleanup in useEffect return: return () => divRef.current?.removeEventListener('scroll', handleScroll); ``` ### When Is ref.current Set? - **Before mount:** `ref.current` is `null` (or your initial value). - **After the component mounts:** React sets `ref.current` to the DOM node. - **After the component unmounts:** React sets `ref.current` back to `null`. So you must not read or use `ref.current` during render for something that affects the render (e.g. reading `ref.current` and rendering based on it). During render, refs may not be attached yet or may be from a previous commit. Use refs in event handlers, `useEffect`, or other callbacks that run after commit. --- ## Callback Refs Instead of passing a ref object, you can pass a **function** to the `ref` prop. React will call that function with the DOM node when the element mounts and with `null` when it unmounts. This is called a callback ref. ### Syntax ```tsx { if (element) { // element is the DOM node; do something on mount element.focus(); } // When element is null, the node unmounted; optional cleanup }} /> ``` ### When React Calls the Callback - **Mount:** React calls your function with the DOM element. - **Unmount:** React calls your function with `null`. So you can run setup when the node is attached and cleanup when it's detached, all in one place. ### Use Cases for Callback Refs **1. Run logic when the node is mounted (e.g. focus):** ```tsx { el?.focus(); }} /> ``` **2. Store the node in your own ref and do cleanup on unmount:** ```tsx function MeasuredDiv() { const [height, setHeight] = useState(0); const setRef = useCallback((node: HTMLDivElement | null) => { if (!node) return; const observer = new ResizeObserver(() => { setHeight(node.getBoundingClientRect().height); }); observer.observe(node); // We need to store the observer to disconnect later. // Often people use a ref for the observer and disconnect in useEffect cleanup, // or use a callback ref that stores observer on the node (hacky) or in a ref. return () => observer.disconnect(); }, []); return

Height: {height}px

; } ``` In practice, storing the observer in a ref and disconnecting in `useEffect` cleanup is cleaner; the callback ref is still useful when you need the exact moment of mount/unmount. **3. Dynamic ref (one ref, many possible elements):** ```tsx function DynamicRef({ condition }: { condition: boolean }) { const ref = useRef(null); const setRef = (el: HTMLDivElement | HTMLSpanElement | null) => { ref.current = el; }; return condition ?

: B; } ``` Here the same ref is attached to different element types depending on `condition`; a callback ref lets you assign whatever is currently mounted to `ref.current`. ### Callback Ref and State Updates If you do something like `setState` inside a callback ref, React may warn or you can get extra renders, because ref callbacks can be called at times that trigger commits. Prefer using callback refs for reading the node or storing it in a ref, and do state updates in `useEffect` based on that ref when possible. --- ## Ref Forwarding (forwardRef) By default, function components don't accept a `ref` prop—React doesn't pass it through like other props. If you want a wrapper component to pass the ref down to a DOM node (or another component that accepts refs), you use `forwardRef`. ### The Problem ```tsx const Input = (props: React.ComponentProps<'input'>) => ; function Form() { const inputRef = useRef(null); return ( <> {/* ref is not forwarded; inputRef.current stays null */} ); } ``` Here `Input` is a function component, so `ref` is not passed to the inner ``. `inputRef.current` remains `null`. ### The Solution: forwardRef `forwardRef` wraps your component so it receives `ref` as the second argument and you can attach it to a child: ```tsx const Input = forwardRef>((props, ref) => { return ; }); function Form() { const inputRef = useRef(null); return ( <> ); } ``` Now `inputRef.current` is the underlying `` DOM element. ### When to Use forwardRef - **Wrapper components:** You're wrapping a native element or a library component and want the parent to get a ref to the inner DOM/node. - **Design systems:** Generic components (inputs, buttons) often forward refs so consumers can focus, measure, or integrate with form libraries. - **Libraries:** If your component wraps a DOM node or another ref-accepting component, forwarding refs is the standard way to expose that node. ### forwardRef with TypeScript In TypeScript you pass two generic arguments to `forwardRef`: the type of the DOM element (or imperative handle) the ref will point to, and the props type: ```tsx import { forwardRef } from 'react'; type InputProps = JSX.IntrinsicElements['input']; const Input = forwardRef( (props, ref) => { return ; } ); ``` `forwardRef` means: the ref forwarded to this component will be a `Ref`, and the component accepts `InputProps`. TypeScript then checks that you pass `ref` to an element that is an `HTMLInputElement`. For other elements use `HTMLDivElement`, `HTMLButtonElement`, etc. ### Don't Overuse forwardRef Only use `forwardRef` when a parent actually needs a ref to the inner node or to an imperative handle. If the component's API is purely declarative (props in, UI out), you usually don't need to forward refs. --- ## useImperativeHandle Sometimes the parent doesn't need the raw DOM node; it needs a **custom API** (e.g. "focus the first invalid field" or "scroll to the end"). You can expose a custom handle with `useImperativeHandle` and a forwarded ref. ### Why Not Just Forward the DOM Node? Forwarding the DOM node gives the parent full access. That can be fine. But sometimes you want to hide implementation details and expose only specific actions (e.g. `focusFirstError()` instead of the parent reaching into `formRef.current.querySelector(...)`). `useImperativeHandle` lets the child define what the ref's `.current` is. ### Basic Example Define the shape of the imperative handle so the parent gets correct types: ```tsx type FancyInputHandle = { focus: () => void; scrollIntoView: () => void; }; const FancyInput = forwardRef>((props, ref) => { const inputRef = useRef(null); useImperativeHandle(ref, () => ({ focus: () => { inputRef.current?.focus(); }, scrollIntoView: () => { inputRef.current?.scrollIntoView({ behavior: 'smooth' }); } })); return ; }); function Parent() { const fancyRef = useRef(null); return ( <> ); } ``` Here the parent's `fancyRef.current` is not the ``; it's the object returned from the function you passed to `useImperativeHandle`: `{ focus, scrollIntoView }`. So the parent can call `fancyRef.current.focus()` or `fancyRef.current.scrollIntoView()` without touching the DOM directly. ### Signature ```ts useImperativeHandle(ref, createHandle, [dependencies]); ``` - **ref:** The ref that was forwarded to this component. - **createHandle:** A function that returns the object you want to assign to `ref.current`. This runs when the ref is attached and when dependencies change. - **dependencies (optional):** When they change, `createHandle` runs again and the ref is updated. Omit to run only on mount. ### Form Example: Expose focusFirstError Type the ref as an object with the imperative methods so the parent gets autocomplete and type safety: ```tsx type FormWithRefHandle = { focusFirstError: () => void; }; const FormWithRef = forwardRef void }>( ({ children, onSubmit }, ref) => { const formRef = useRef(null); useImperativeHandle(ref, () => ({ focusFirstError: () => { const firstInvalid = formRef.current?.querySelector(':invalid'); if (firstInvalid && typeof firstInvalid.focus === 'function') { firstInvalid.focus(); } } })); return ( ); } ); function Parent() { const formRef = useRef(null); function handleSubmit(e: React.FormEvent) { e.preventDefault(); if (!validateForm()) { formRef.current?.focusFirstError(); } } return ( ); } ``` The parent only knows about `focusFirstError`; it doesn't need to know how the form finds the first invalid field. ### When to Use useImperativeHandle - You want the parent to trigger an action (focus, scroll, reset) without exposing the DOM or internal structure. - You're building a reusable component (input, form, list) and want a small, stable imperative API. Use it sparingly; prefer declarative props (e.g. `autoFocus`, `scrollToItemId`) when that's enough. --- ## Refs and Class Components In class components, refs were created with `React.createRef()` and attached to the `ref` prop. You might see this in legacy code or documentation. ### createRef (class components) ```tsx class OldInput extends React.Component { inputRef = React.createRef(); focusInput = () => { this.inputRef.current?.focus(); }; render() { return ( <> ); } } ``` `createRef()` returns an object `{ current: null }`. Once per component instance, so it's stable. In function components you use `useRef` instead; you don't use `createRef` in function components (it would create a new ref on every render). ### Legacy String Refs (avoid) Older React had string refs: `ref="inputRef"` and then `this.refs.inputRef`. They are deprecated and removed in React 19. Don't use them. If you see them, replace with `createRef` (class) or `useRef` (function). --- ## Practical Use Cases ### Focus Management **Focus an input on mount:** ```tsx function SearchBox() { const inputRef = useRef(null); useEffect(() => { inputRef.current?.focus(); }, []); return ; } ``` **Focus first invalid field after submit:** Use the form + `useImperativeHandle` pattern above, or in a simple case: ```ts formRef.current?.querySelector(':invalid')?.focus(); ``` **Focus trap in a modal:** Store the first and last focusable elements in refs (or derive them in an effect), and on Tab from the last one, focus the first. This is often done with a small hook or library (e.g. focus-trap-react). ### Scroll to Element **Scroll a list to the bottom when new items are added:** ```tsx const listRef = useRef(null); useEffect(() => { if (items.length && listRef.current) { listRef.current.scrollTo(0, listRef.current.scrollHeight); } }, [items.length]); ``` **Scroll a specific item into view:** ```tsx const itemRefs = useRef<(HTMLElement | null)[]>([]); function scrollToIndex(index: number) { itemRefs.current[index]?.scrollIntoView({ behavior: 'smooth', block: 'nearest' }); } ``` When rendering a list, assign: `ref={(el) => (itemRefs.current[i] = el)}`. ### Measuring Elements **Measure after layout (e.g. for responsive logic):** ```tsx const divRef = useRef(null); const [width, setWidth] = useState(0); useEffect(() => { const node = divRef.current; if (!node) return; const observer = new ResizeObserver((entries: ResizeObserverEntry[]) => { setWidth(entries[0].contentRect.width); }); observer.observe(node); return () => observer.disconnect(); }, []); return

Width: {width}px

; ``` You can also use `getBoundingClientRect()` in effects or in a ResizeObserver callback; refs give you the node to observe. ### Third-Party Libraries (Charts, Maps, etc.) Many libraries expect a DOM container: you give them a `div`, they render into it. Use a ref to hold that div: ```tsx const chartContainerRef = useRef(null); useEffect(() => { const el = chartContainerRef.current; if (!el) return; const chart = new ThirdPartyChart(el, options); return () => chart.destroy(); }, [/* options that should recreate chart */]); return

; ``` Same idea for maps, editors, or any imperative API that takes an element. ### Animation (e.g. GSAP) Animation libraries often need the DOM node: ```tsx const elRef = useRef(null); useEffect(() => { const el = elRef.current; if (!el) return; gsap.fromTo(el, { opacity: 0 }, { opacity: 1, duration: 0.5 }); }, []); return

Animated

; ``` Refs let you pass the node to the animation API without storing it in state. ### Avoiding Stale Closures in Effects Sometimes you need the latest callback or value inside an effect but don't want to re-run the effect when it changes. You can keep the latest value in a ref and read it inside the effect: ```tsx const latestCallback = useRef(callback); latestCallback.current = callback; useEffect(() => { const id = setInterval(() => { latestCallback.current(); }, 1000); return () => clearInterval(id); }, []); // Empty deps; effect runs once, but latestCallback.current is always up to date ``` In TypeScript, type the ref to match the callback: `useRef<(arg: T) => void>(callback)` so `latestCallback.current()` is correctly typed. This pattern is useful for intervals, subscriptions, or event handlers that must always see the latest props/state without re-subscribing. --- ## Common Pitfalls and Gotchas ### Reading ref.current During Render Don't use `ref.current` to decide what to render. During render, refs may not be updated yet (they're updated after commit). So: ```tsx // Bad: ref.current might be null or stale during render function Bad() { const ref = useRef(null); return

{ref.current ? 'Mounted' : 'Not mounted'}

; } ``` Use state or a layout effect to react to "node is mounted" if you need to show something based on that. ### Refs on Function Components (Without forwardRef) If you pass a ref to a custom function component that doesn't use `forwardRef`, the ref will stay `null` (or whatever you set). React doesn't forward refs through function components by default. Use `forwardRef` when the component should expose a DOM node or an imperative handle. ### Cleanup of Refs in Effects When you store something in a ref that has cleanup (timer, subscription, observer), do the cleanup in the effect's return. The ref itself doesn't need "cleaning"; it's the side effect you set up (e.g. `setInterval`, `ResizeObserver`) that must be torn down. Example: ```tsx useEffect(() => { const node = divRef.current; if (!node) return; const observer = new ResizeObserver(/* ... */); observer.observe(node); return () => observer.disconnect(); }, []); ``` ### Conditional Refs If you attach a ref conditionally (e.g. `ref={condition ? myRef : null}`), React will call the ref with `null` when the condition becomes false (unmount) and with the new node when it becomes true again. That's valid. Just make sure any effect that uses the ref handles the case where the ref is null or the element type changes (e.g. you had one node, now you have another). ### Ref Object Identity The ref **object** (e.g. the result of `useRef`) is stable. The **value** of `.current` can change (React sets it when the element mounts/unmounts, or you set it). So when you pass the ref to a child, you're passing the same object; the child or React will assign `.current`. Don't create a new ref object inside render (e.g. `ref={{ current: null }}`); that would be a new object every time and break React's ref handling. --- ## Summary and Quick Reference ### When to Use What | Goal | Tool | |------|------| | Hold a DOM node or mutable value without re-renders | `useRef` | | Parent needs ref to a child's DOM node | `forwardRef` | | Parent needs a custom API (focus, scroll) instead of raw DOM | `useImperativeHandle` + `forwardRef` | | Run logic when node mounts/unmounts or need one ref for multiple elements | Callback ref | | Store previous value or latest callback for effects | `useRef` | ### Refs vs State (Reminder) - **State:** Drives UI; updates trigger re-render. Use for what the user sees and for declarative behavior. - **Ref:** Persists across renders; updates do not trigger re-render. Use for DOM nodes, timers, subscriptions, previous values, and imperative handles. ### Key Rules 1. Don't read `ref.current` during render to decide what to render. 2. Don't store DOM nodes in state; use refs. 3. Use optional chaining when calling methods on `ref.current` (it can be null). 4. Clean up any side effects you set up in effects (observers, listeners, intervals) in the effect's return; the ref is just a reference. 5. To expose a ref from a custom component, use `forwardRef` (and optionally `useImperativeHandle`). ### Cheat Sheet ```tsx // Create ref (type for DOM element or your handle) const ref = useRef(null); // Attach to DOM

// Read in effect or handler ref.current?.focus(); // Callback ref (element type is inferred from the host element)

{ ref.current = el; el?.focus(); }} /> // Forward ref (ElementType, Props) const MyInput = forwardRef>((props, ref) => ( )); // Imperative handle (type the exposed API) useImperativeHandle(ref, () => ({ focus: () => inputRef.current?.focus() })); ``` Refs are a small API with a few rules. Use them when you need to step outside the declarative model for DOM access or mutable identity, and you'll keep your React code clean and predictable.

React Refs: The Complete Deep Dive