diff --git a/docs/docs/refs-and-the-dom.md b/docs/docs/refs-and-the-dom.md index 85a0429eb408b..8b86332ea92c9 100644 --- a/docs/docs/refs-and-the-dom.md +++ b/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 ( +