adds indirect refs to docs (#9528)

* adds indirect refs to docs

* Add more info

* Explain clearer

* Rephrase

* Update refs-and-the-dom.md

* Update refs-and-the-dom.md

* Update refs-and-the-dom.md

* Update refs-and-the-dom.md

* Update refs-and-the-dom.md

* Update refs-and-the-dom.md

* Update refs-and-the-dom.md

* Update refs-and-the-dom.md

* Update refs-and-the-dom.md

* Update refs-and-the-dom.md

* Update refs-and-the-dom.md

(cherry picked from commit 14fa8a5)

docs/docs/refs-and-the-dom.md

@@ -25,6 +25,10 @@ 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](/react/docs/lifting-state-up.html) guide for examples of this.
+
 ### Adding a Ref to a DOM Element
 
 React supports a special attribute that you can attach to any component. The `ref` attribute takes a callback function, and the callback will be executed immediately after the component is mounted or unmounted.
@@ -141,9 +145,76 @@ function CustomTextInput(props) {
 }
 ```
 
-### Don't Overuse Refs
+### Exposing DOM Refs to Parent Components
 
-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](/react/docs/lifting-state-up.html) guide for examples of this.
+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 to the child component](#adding-a-ref-to-a-class-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 functional components.
+
+Instead, in such cases we recommend exposing a special prop on the child. The child would take a function prop with an arbitrary name (e.g. `inputRef`) and attach it to the DOM node as a `ref` attribute. This lets the parent pass its ref callback to the child's DOM node through the component in the middle.
+
+This works both for classes and for functional components.
+
+```javascript{4,13}
+function CustomTextInput(props) {
+ return (
+ <div>
+ <input ref={props.inputRef} />
+ </div>
+ );
+}
+
+class Parent extends React.Component {
+ render() {
+ return (
+ <CustomTextInput
+ inputRef={el => this.inputElement = el}
+ />
+ );
+ }
+}
+```
+
+In the example above, `Parent` passes its ref callback as an `inputRef` prop to the `CustomTextInput`, and the `CustomTextInput` passes the same function as a special `ref` attribute to the `<input>`. As a result, `this.inputElement` in `Parent` will be set to the DOM node corresponding to the `<input>` element in the `CustomTextInput`.
+
+Note that the name of the `inputRef` prop in the above example has no special meaning, as it is a regular component prop. However, using the `ref` attribute on the `<input>` itself is important, as it tells React to attach a ref to its DOM node.
+
+This works even though `CustomTextInput` is a functional component. Unlike the special `ref` attribute which can [only be specified for DOM elements and for class components](#refs-and-functional-components), there are no restrictions on regular component props like `inputRef`.
+
+Another benefit of this pattern is that it works several components deep. For example, imagine `Parent` didn't need that DOM node, but a component that rendered `Parent` (let's call it `Grandparent`) needed access to it. Then we could let the `Grandparent` specify the `inputRef` prop to the `Parent`, and let `Parent` "forward" it to the `CustomTextInput`:
+
+```javascript{4,12,22}
+function CustomTextInput(props) {
+ return (
+ <div>
+ <input ref={props.inputRef} />
+ </div>
+ );
+}
+
+function Parent(props) {
+ return (
+ <div>
+ My input: <CustomTextInput inputRef={props.inputRef} />
+ </div>
+ );
+}
+
+
+class Grandparent extends React.Component {
+ render() {
+ return (
+ <Parent
+ inputRef={el => this.inputElement = el}
+ />
+ );
+ }
+}
+```
+
+Here, the ref callback is first specified by `Grandparent`. It is passed to the `Parent` as a regular prop called `inputRef`, and the `Parent` passes it to the `CustomTextInput` as a prop too. Finally, the `CustomTextInput` reads the `inputRef` prop and attaches the passed function as a `ref` attribute to the `<input>`. As a result, `this.inputElement` in `Grandparent` will be set to the DOM node corresponding to the `<input>` element in the `CustomTextInput`.
+
+All things considered, we advise against exposing DOM nodes whenever possible, but this 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()`](/react/docs/react-dom.html#finddomnode), but it is discouraged.
 
 ### Legacy API: String Refs