Short answer:

React guarantees that refs are set before componentDidMount or componentDidUpdate hooks. But only for children that actually got rendered.

componentDidMount() {
  // can use any refs here
}

componentDidUpdate() {
  // can use any refs here
}

render() {
  // as long as those refs were rendered!
  return <div ref={/* ... */} />;
}

Note this doesn’t mean “React always sets all refs before these hooks run”.
Let’s look at some examples where the refs don’t get set.

---

Refs don’t get set for elements that weren’t rendered

React will only call ref callbacks for elements that you actually returned from render.

This means that if your code looks like

render() {
  if (this.state.isLoading) {
    return <h1>Loading</h1>;
  }

  return <div ref={this._setRef} />;
}

and initially this.state.isLoading is true, you should not expect this._setRef to be called before componentDidMount.

This should make sense: if your first render returned <h1>Loading</h1>, there’s no possible way for React to know that under some other condition it returns something else that needs a ref to be attached. There is also nothing to set the ref to: the <div> element was not created because the render() method said it shouldn’t be rendered.

So with this example, only componentDidMount will fire. However, when this.state.loading changes to false, you will see this._setRef attached first, and then componentDidUpdate will fire.

---

Watch out for other components

Note that if you pass children with refs down to other components there is a chance they’re doing something that prevents rendering (and causes the issue).

For example, this:

<MyPanel>
  <div ref={this.setRef} />
</MyPanel>

wouldn’t work if MyPanel did not include props.children in its output:

function MyPanel(props) {
  // ignore props.children
  return <h1>Oops, no refs for you today!</h1>;
}

Again, it’s not a bug: there would be nothing for React to set the ref to because the DOM element was not created.

---

Refs don’t get set before lifecycles if they’re passed to a nested ReactDOM.render()

Similar to the previous section, if you pass a child with a ref to another component, it’s possible that this component may do something that prevents attaching the ref in time.

For example, maybe it’s not returning the child from render(), and instead is calling ReactDOM.render() in a lifecycle hook. You can find an example of this here. In that example, we render:

<MyModal>
  <div ref={this.setRef} />
</MyModal>

But MyModal performs a ReactDOM.render() call in its componentDidUpdate lifecycle method:

componentDidUpdate() {
  ReactDOM.render(this.props.children, this.targetEl);
}

render() {
  return null;
}

Since React 16, such top-level render calls during a lifecycle will be delayed until lifecycles have run for the whole tree. This would explain why you’re not seeing the refs attached in time.

The solution to this problem is to use
portals instead of nested ReactDOM.render calls:

render() {
  return ReactDOM.createPortal(this.props.children, this.targetEl);
}

This way our <div> with a ref is actually included in the render output.

So if you encounter this issue, you need to verify there’s nothing between your component and the ref that might delay rendering children.

Don’t use setState to store refs

Make sure you are not using setState to store the ref in ref callback, as it’s asynchronous and before it’s “finished”, componentDidMount will be executed first.

---

Still an Issue?

If none of the tips above help, file an issue in React and we will take a look.