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.
const inputRef = useRef(null); <input ref={inputRef} /> <button onClick={() => inputRef.current.focus()}>Focus</button>
Try it
Syntax
<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.currentduring 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 = xis invisible to React. If the UI must update, use state. This is also whyuseRefis 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 readreffrom its props, andforwardRefis 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
Mapkeyed by id, rather than an array of refs created in a loop (hooks cannot be called in loops). - Exposing less. With
useImperativeHandlea 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.