Forwarding Refs

Why Ref Forwarding?

Consider a FancyButton component that renders the native button DOM element:

RES
// FancyButton.res

@react.component
let make = (~children) => {
  <button className="FancyButton">
    children
  </button>
}

React components hide their implementation details, including their rendered output. Other components using FancyButton usually will not need to obtain a ref to the inner button DOM element. This is good because it prevents components from relying on each other’s DOM structure too much.

Although such encapsulation is desirable for application-level components like FeedStory or Comment, it can be inconvenient for highly reusable “leaf” components like FancyButton or MyTextInput. These components tend to be used throughout the application in a similar manner as a regular DOM button and input, and accessing their DOM nodes may be unavoidable for managing focus, selection, or animations.

There are currently two strategies on forwarding refs through a component. In ReScript and React we strongly recommend passing your ref as a prop, but there is also a dedicated API called React.forwardRef.

We will discuss both methods in this document.

Forward Refs via Props

A React.ref can be passed down like any other prop. The component will take care of forwarding the ref to the right DOM element.

No new concepts to learn!

In the example below, FancyInput defines a prop inputRef that will be forwarded to its input element:

RES
// App.res

module FancyInput = {
  @react.component
  let make = (~children, ~inputRef: ReactDOM.domRef) =>
    <div> <input type_="text" ref=inputRef /> children </div>
}

@send external focus: Dom.element => unit = "focus"

@react.component
let make = () => {
  let input = React.useRef(Js.Nullable.null)

  let focusInput = () =>
    input.current
    ->Js.Nullable.toOption
    ->Belt.Option.forEach(input => input->focus)

  let onClick = _ => focusInput()

  <div>
    <FancyInput inputRef={ReactDOM.Ref.domRef(input)}>
      <button onClick> {React.string("Click to focus")} </button>
    </FancyInput>
  </div>
}

We use the ReactDOM.domRef type to represent our inputRef. We pass our ref in the exact same manner as we'd do a DOM ref attribute (<input ref={ReactDOM.Ref.domRef(myRef)} />).

[Discouraged] React.forwardRef

Note: We discourage this method since it will likely go away at some point, and doesn't yield any obvious advantages over the previously mentioned ref prop passing.

React.forwardRef offers a way to "emulate a ref prop" within custom components. Internally the component will forward the passed ref value to the target DOM element instead.

This is how the previous example would look like with the React.forwardRef approach:

// App.res

module FancyInput = {
  @react.component
  let make = React.forwardRef((~className=?, ~children, ref) =>
    <div>
      <input
        type_="text"
        ?className
        ref=?{Js.Nullable.toOption(ref)->Belt.Option.map(ReactDOM.Ref.domRef)}
      />
      children
    </div>
  )
}

@send external focus: Dom.element => unit = "focus"

@react.component
let make = () => {
  let input = React.useRef(Js.Nullable.null)

  let focusInput = () =>
    input.current->Js.Nullable.toOption->Belt.Option.forEach(input => input->focus)

  let onClick = _ => focusInput()

  <div>
    <FancyInput className="fancy" ref=input>
      <button onClick> {React.string("Click to focus")} </button>
    </FancyInput>
  </div>
}

Note: Our @react.component decorator transforms our labeled argument props within our React.forwardRef function in the same manner as our classic make function.

This way, components using FancyInput can get a ref to the underlying input DOM node and access it if necessary—just like if they used a DOM input directly.

Note for Component Library Maintainers

When you start using ref forwarding in a component library, you should treat it as a breaking change and release a new major version of your library. This is because your library likely has an observably different behavior (such as what refs get assigned to, and what types are exported), and this can break apps and other libraries that depend on the old behavior.