Skip to content
Tutorials Center
My learning

Topics

React Reference ยท Props and Attributes

React ref prop

Reference for the React ref prop: get a DOM node with useRef, pass refs to function components as a normal prop in React 19, and know when not to use refs.

ref is a special prop that gives you direct access to something React created. On a built-in element such as <input>, it gives you the real DOM node; on a class component, the component instance. You use it for the few things React's declarative model cannot express: focusing an input, scrolling to an element, measuring size, playing a video, or calling a method on a third-party widget.

The usual way to make a ref is the useRef hook, which returns an object { current: null }. React fills in current when the element is added to the page and sets it back to null when the element is removed. A ref can also be a function, called a ref callback.

JSX
const inputRef = useRef(null);

<input ref={inputRef} />
<button onClick={() => inputRef.current.focus()}>Focus</button>

Try it

Focus and select with a ref
ref as a prop on a function component

Syntax

JSX
<element ref={refObject} />
<element ref={(node) => { /* attach */ }} />
<Component ref={refObject} />
Name Description
ref as an object A value from useRef(null) or createRef(). React sets ref.current to the DOM node (or class instance) when it mounts and to null when it unmounts.
ref as a function Called with the node on attach. See Ref callback functions.

Returns: nothing; ref is not passed down to the DOM. On function components in React 19, ref is an ordinary prop (props.ref), so the component decides where to forward it.

Errors / edge cases: ref.current is null during the first render and for elements that are not rendered. Using ref on a function component in React 18 and earlier logs a warning unless the component is wrapped in forwardRef.

Usage notes

  • Do not read or write ref.current during rendering. The value is not set yet on the first render, and changing it during render breaks React's assumptions. Use refs in event handlers and effects.
  • Refs are an escape hatch. Do not use them to read or change what you can express with props and state, such as the value of an input, or whether something is visible.
  • Changing a ref does not re-render. ref.current = x is invisible to React. If the UI must update, use state. This is also why useRef is handy for values that must persist between renders without causing them, such as timer ids.
  • Avoid editing DOM managed by React. Focusing, scrolling and measuring are safe. Adding, removing or rewriting children of a node React renders can desynchronize the tree.
  • React 19 and forwardRef. In React 19 a function component can read ref from its props, and forwardRef is no longer needed for new code (see ref as a prop). It still works and will be deprecated later.
  • Class components receive an instance in ref.current, giving access to methods. Prefer props and callbacks to calling instance methods.
  • Refs to lists. Use a callback ref that stores nodes in a Map keyed by id, rather than an array of refs created in a loop (hooks cannot be called in loops).
  • Exposing less. With useImperativeHandle a component can expose just a few methods instead of its whole DOM node.
  • StrictMode. In development, React mounts, unmounts and mounts components once more to catch bugs; refs are detached and attached again, so attach and detach logic must be symmetric.