Add a section "Displaying a custom name in DevTools"

Author: koba04

content/blog/2018-03-29-react-v-16-3.md

@@ -52,6 +52,8 @@ HOCs typically [pass props through](/docs/higher-order-components.html#conventio
 The new `forwardRef` API solves this problem by providing a way for us to intercept a `ref` and forward it as a normal prop:
 `embed:16-3-release-blog-post/forward-ref-example.js`
 
+[Learn more about the forwardRef API here.](/docs/forwarding-refs.html)
+
 ## Component Lifecycle Changes
 
 React's class component API has been around for years with little change. However, as we add support for more advanced features (such as [error boundaries](/docs/react-component.html#componentdidcatch) and the upcoming [async rendering mode](/blog/2018/03/01/sneak-peek-beyond-react-16.html)) we stretch this model in ways that it was not originally intended.

content/docs/forwarding-refs.md

@@ -20,3 +20,18 @@ This means that refs intended for our `FancyButton` component will actually be a
 Fortunately, we can explicitly forward refs to the inner `FancyButton` component using the `React.forwardRef` API. `React.forwardRef` accepts a render function that receives `props` and `ref` parameters and returns a React node. For example:
 `embed:forwarding-refs/log-props-after.js`
 
+## Displaying a custom name in DevTools
+
+`React.forwardRef` accepts a render function. React DevTools uses this function to determine what to display for the ref forwarding component.
+
+For example, the following component will appear as "*ForwardRef*" in the DevTools:
+
+`embed:forwarding-refs/wrapped-component.js`
+
+If you name the render function, DevTools will include its name (e.g. "*ForwardRef(myFunction)*"):
+
+`embed:forwarding-refs/wrapped-component-with-function-name.js`
+
+You can even set the function's `displayName` property to include the component you're wrapping:
+
+`embed:forwarding-refs/customized-display-name.js`

examples/forwarding-refs/customized-display-name.js

@@ -0,0 +1,17 @@
+function logProps(Component) {
+  class LogProps extends React.Component {
+    // ...
+  }
+
+  function forwardRef(props, ref) {
+    return <LogProps {...props} forwardedRef={ref} />;
+  }
+
+  // Give this component a more helpful display name in DevTools.
+  // e.g. "ForwardRef(logProps(MyComponent))"
+  // highlight-range{1-2}
+  const name = Component.displayName || Component.name;
+  forwardRef.displayName = `logProps(${name})`;
+
+  return React.forwardRef(forwardRef);
+}

examples/forwarding-refs/log-props-after.js

@@ -19,16 +19,7 @@ function logProps(Component) {
   // We can pass it along to LogProps as a regular prop, e.g. "forwardedRef"
   // And it can then be attached to the Component.
   // highlight-range{1-3}
-  function forwardRef(props, ref) {
+  return React.forwardRef((props, ref) => {
     return <LogProps {...props} forwardedRef={ref} />;
-  }
-
-  // These next lines are not necessary,
-  // But they do give the component a better display name in DevTools,
-  // e.g. "ForwardRef(logProps(MyComponent))"
-  // highlight-range{1-2}
-  const name = Component.displayName || Component.name;
-  forwardRef.displayName = `logProps(${name})`;
-
-  return React.forwardRef(forwardRef);
+  });
 }

examples/forwarding-refs/wrapped-component-with-function-name.js

@@ -0,0 +1,5 @@
+const WrappedComponent = React.forwardRef(
+  function myFunction(props, ref) {
+    return <LogProps {...props} forwardedRef={ref} />;
+  }
+);

examples/forwarding-refs/wrapped-component.js

@@ -0,0 +1,3 @@
+const WrappedComponent = React.forwardRef((props, ref) => {
+  return <LogProps {...props} forwardedRef={ref} />;
+});