Refs and the DOM

Refs provide a way to access DOM nodes or React elements created in the render method.

In the typical React dataflow, props are the only way that parent components interact with their children. To modify a child, you re-render it with new props. However, there are a few cases where you need to imperatively modify a child outside of the typical dataflow. The child to be modified could be an instance of a React component, or it could be a DOM element. For both of these cases, React provides an escape hatch.

When to Use Refs

There are a few good use cases for refs:

• Managing focus, text selection, or media playback.
• Triggering imperative animations.
• Integrating with third-party DOM libraries.

Avoid using refs for anything that can be done declaratively.

For example, instead of exposing open() and close() methods on a Dialog component, pass an isOpen prop to it.

Don’t Overuse Refs

Your first inclination may be to use refs to “make things happen” in your app. If this is the case, take a moment and think more critically about where state should be owned in the component hierarchy. Often, it becomes clear that the proper place to “own” that state is at a higher level in the hierarchy. See the Lifting State Up guide for examples of this.

Note

The examples below have been updated to use the React.createRef() API introduced in React 16.3. If you are using an earlier release of React, we recommend using callback refs instead.

Creating Refs

Refs are created using the useRef hook and attached to React elements via the ref attribute.

function MyComponent() {
  const myRef = useRef(null);  
  return <div ref={myRef} />;}

Accessing Refs

When a ref is passed to an element, a reference to the node becomes accessible at the current attribute of the ref.

const node = myRef.current;

The value of the ref differs depending on the type of the node:

• When the ref attribute is used on an HTML element, the ref created with useRef receives the underlying DOM element as its current property.
• When the ref attribute is used on a custom class component, the ref object receives the mounted instance of the component as its current.

The examples below demonstrate the differences.

Adding a Ref to a DOM Element

This code uses a ref to store a reference to a DOM node:

function CustomTextInput() {
  // create a ref to store the textInput DOM element
  const textInput = useRef(null);
  function focusTextInput() {
    // Explicitly focus the text input using the raw DOM API
    // Note: we're accessing "current" to get the DOM node
    textInput.current.focus();  }

  // tell React that we want to associate the <input> ref
  // with the `textInput` that we created in the constructor
  return (
    <div>
      <input
        type="text"
        ref={textInput} />      <input
        type="button"
        value="Focus the text input"
        onClick={focusTextInput}
      />
    </div>
  );
}

React will assign the current property with the DOM element when the component mounts, and assign it back to null when it unmounts. ref updates happen before useEffect functions get called.

Adding a Ref to a Component

If we wanted to wrap the CustomTextInput above to simulate it being clicked immediately after mounting, we could use a ref to get access to the custom input and call its focusTextInput function manually:

function AutoFocusTextInput() {
  const textInput = useRef(null);
  useEffect(() => {
    textInput.current.focusTextInput();  }, [])

  return (
    <CustomTextInput ref={textInput} />  );
}

Exposing DOM Refs to Parent Components

In rare cases, you might want to have access to a child’s DOM node from a parent component. This is generally not recommended because it breaks component encapsulation, but it can occasionally be useful for triggering focus or measuring the size or position of a child DOM node.

While you could add a ref to the child component, this is not an ideal solution, as you would only get a component instance rather than a DOM node. Additionally, this wouldn’t work with function components.

If you use React 16.3 or higher, we recommend to use ref forwarding for these cases. Ref forwarding lets components opt into exposing any child component’s ref as their own. You can find a detailed example of how to expose a child’s DOM node to a parent component in the ref forwarding documentation.

If you use React 16.2 or lower, or if you need more flexibility than provided by ref forwarding, you can use this alternative approach and explicitly pass a ref as a differently named prop.

When possible, we advise against exposing DOM nodes, but it can be a useful escape hatch. Note that this approach requires you to add some code to the child component. If you have absolutely no control over the child component implementation, your last option is to use findDOMNode(), but it is discouraged and deprecated in StrictMode.