diff --git a/content/community/conferences.md b/content/community/conferences.md
index e138b119a..ea8613c78 100644
--- a/content/community/conferences.md
+++ b/content/community/conferences.md
@@ -57,6 +57,11 @@ July 15-21, 2019. New York City, USA
[Website](https://reactweek.nyc) - [Twitter](https://twitter.com/ReactWeek)
+### React Rally 2019
+August 22-23, 2019. Salt Lake City, USA.
+
+[Website](https://www.reactrally.com/) - [Twitter](https://twitter.com/ReactRally) - [Instagram](https://www.instagram.com/reactrally/)
+
### ComponentsConf 2019 {#componentsconf-2019}
September 6, 2019 in Melbourne, Australia
[Website](https://www.componentsconf.com.au/) - [Twitter](https://twitter.com/componentsconf)
diff --git a/content/docs/hooks-faq.md b/content/docs/hooks-faq.md
index 9016fa7f4..7d2953293 100644
--- a/content/docs/hooks-faq.md
+++ b/content/docs/hooks-faq.md
@@ -41,6 +41,7 @@ This page answers some of the frequently asked questions about [Hooks](/docs/hoo
* [How do I implement getDerivedStateFromProps?](#how-do-i-implement-getderivedstatefromprops)
* [Is there something like forceUpdate?](#is-there-something-like-forceupdate)
* [Can I make a ref to a function component?](#can-i-make-a-ref-to-a-function-component)
+ * [How can I measure a DOM node?](#how-can-i-measure-a-dom-node)
* [What does const [thing, setThing] = useState() mean?](#what-does-const-thing-setthing--usestate-mean)
* **[Performance Optimizations](#performance-optimizations)**
* [Can I skip an effect on updates?](#can-i-skip-an-effect-on-updates)
@@ -451,6 +452,60 @@ Try to avoid this pattern if possible.
While you shouldn't need this often, you may expose some imperative methods to a parent component with the [`useImperativeHandle`](/docs/hooks-reference.html#useimperativehandle) Hook.
+### How can I measure a DOM node? {#how-can-i-measure-a-dom-node}
+
+In order to measure the position or size of a DOM node, you can use a [callback ref](/docs/refs-and-the-dom.html#callback-refs). React will call that callback whenever the ref gets attached to a different node. Here is a [small demo](https://codesandbox.io/s/l7m0v5x4v9):
+
+```js{4-8,12}
+function MeasureExample() {
+ const [height, setHeight] = useState(0);
+
+ const measuredRef = useCallback(node => {
+ if (node !== null) {
+ setHeight(node.getBoundingClientRect().height);
+ }
+ }, []);
+
+ return (
+ <>
+ Hello, world
+ The above header is {Math.round(height)}px tall
+
+ );
+}
+```
+
+We didn't choose `useRef` in this example because an object ref doesn't notify us about *changes* to the current ref value. Using a callback ref ensures that [even if a child component displays the measured node later](https://codesandbox.io/s/818zzk8m78) (e.g. in response to a click), we still get notified about it in the parent component and can update the measurements.
+
+Note that we pass `[]` as a dependency array to `useCallback`. This ensures that our ref callback doesn't change between the re-renders, and so React won't call it unnecessarily.
+
+If you want, you can [extract this logic](https://codesandbox.io/s/m5o42082xy) into a reusable Hook:
+
+```js{2}
+function MeasureExample() {
+ const [rect, ref] = useClientRect();
+ return (
+ <>
+ Hello, world
+ {rect !== null &&
+ The above header is {Math.round(rect.height)}px tall
+ }
+
+ );
+}
+
+function useClientRect() {
+ const [rect, setRect] = useState(null);
+ const ref = useCallback(node => {
+ if (node !== null) {
+ setRect(node.getBoundingClientRect());
+ }
+ }, []);
+ return [rect, ref];
+}
+```
+
+
### What does `const [thing, setThing] = useState()` mean? {#what-does-const-thing-setthing--usestate-mean}
If you're not familiar with this syntax, check out the [explanation](/docs/hooks-state.html#tip-what-do-square-brackets-mean) in the State Hook documentation.
@@ -853,7 +908,7 @@ function Form() {
const [text, updateText] = useState('');
const textRef = useRef();
- useLayoutEffect(() => {
+ useEffect(() => {
textRef.current = text; // Write it to the ref
});
@@ -894,7 +949,7 @@ function useEventCallback(fn, dependencies) {
throw new Error('Cannot call an event handler while rendering.');
});
- useLayoutEffect(() => {
+ useEffect(() => {
ref.current = fn;
}, [fn, ...dependencies]);
diff --git a/content/docs/hooks-reference.md b/content/docs/hooks-reference.md
index 4daf0f191..98c2e14c0 100644
--- a/content/docs/hooks-reference.md
+++ b/content/docs/hooks-reference.md
@@ -97,6 +97,8 @@ const [state, setState] = useState(() => {
If you update a State Hook to the same value as the current state, React will bail out without rendering the children or firing effects. (React uses the [`Object.is` comparison algorithm](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is#Description).)
+Note that React may still need to render that specific component again before bailing out. That shouldn't be a concern because React won't unnecessarily go "deeper" into the tree. If you're doing expensive calculations while rendering, you can optimize them with `useMemo`.
+
### `useEffect` {#useeffect}
```js
@@ -173,12 +175,26 @@ The array of dependencies is not passed as arguments to the effect function. Con
### `useContext` {#usecontext}
```js
-const context = useContext(Context);
+const value = useContext(MyContext);
```
-Accepts a context object (the value returned from `React.createContext`) and returns the current context value, as given by the nearest context provider for the given context.
+Accepts a context object (the value returned from `React.createContext`) and returns the current context value for that context. The current context value is determined by the `value` prop of the nearest `` above the calling component in the tree.
+
+When the nearest `` above the component updates, this Hook will trigger a rerender with the latest context `value` passed to that `MyContext` provider.
+
+Don't forget that the argument to `useContext` must be the *context object itself*:
+
+ * **Correct:** `useContext(MyContext)`
+ * **Incorrect:** `useContext(MyContext.Consumer)`
+ * **Incorrect:** `useContext(MyContext.Provider)`
-When the provider updates, this Hook will trigger a rerender with the latest context value.
+A component calling `useContext` will always re-render when the context value changes. If re-rendering the component is expensive, you can [optimize it by using memoization](https://github.com/facebook/react/issues/15156#issuecomment-474590693).
+
+>Tip
+>
+>If you're familiar with the context API before Hooks, `useContext(MyContext)` is equivalent to `static contextType = MyContext` in a class, or to ``.
+>
+>`useContext(MyContext)` only lets you *read* the context and subscribe to its changes. You still need a `` above in the tree to *provide* the value for this context.
## Additional Hooks {#additional-hooks}
@@ -285,6 +301,8 @@ function Counter({initialCount}) {
If you return the same value from a Reducer Hook as the current state, React will bail out without rendering the children or firing effects. (React uses the [`Object.is` comparison algorithm](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is#Description).)
+Note that React may still need to render that specific component again before bailing out. That shouldn't be a concern because React won't unnecessarily go "deeper" into the tree. If you're doing expensive calculations while rendering, you can optimize them with `useMemo`.
+
### `useCallback` {#usecallback}
```js
@@ -356,7 +374,16 @@ function TextInputWithFocusButton() {
}
```
-Note that `useRef()` is useful for more than the `ref` attribute. It's [handy for keeping any mutable value around](/docs/hooks-faq.html#is-there-something-like-instance-variables) similar to how you'd use instance fields in classes.
+Essentially, `useRef` is like a "box" that can hold a mutable value in its `.current` property.
+
+You might be familiar with refs primarily as a way to [access the DOM](/docs/refs-and-the-dom.html). If you pass a ref object to React with ``, React will set its `.current` property to the corresponding DOM node whenever that node changes.
+
+However, `useRef()` is useful for more than the `ref` attribute. It's [handy for keeping any mutable value around](/docs/hooks-faq.html#is-there-something-like-instance-variables) similar to how you'd use instance fields in classes.
+
+This works because `useRef()` creates a plain JavaScript object. The only difference between `useRef()` and creating a `{current: ...}` object yourself is that `useRef` will give you the same ref object on every render.
+
+Keep in mind that `useRef` *doesn't* notify you when its content changes. Mutating the `.current` property doesn't cause a re-render. If you want to run some code when React attaches or detaches a ref to a DOM node, you may want to use a [callback ref](/docs/hooks-faq.html#how-can-i-measure-a-dom-node) instead.
+
### `useImperativeHandle` {#useimperativehandle}
@@ -389,7 +416,11 @@ Prefer the standard `useEffect` when possible to avoid blocking visual updates.
> Tip
>
-> If you're migrating code from a class component, `useLayoutEffect` fires in the same phase as `componentDidMount` and `componentDidUpdate`, so if you're unsure of which effect Hook to use, it's probably the least risky.
+> If you're migrating code from a class component, note `useLayoutEffect` fires in the same phase as `componentDidMount` and `componentDidUpdate`. However, **we recommend starting with `useEffect` first** and only trying `useLayoutEffect` if that causes a problem.
+>
+>If you use server rendering, keep in mind that *neither* `useLayoutEffect` nor `useEffect` can run until the JavaScript is downloaded. This is why React warns when a server-rendered component contains `useLayoutEffect`. To fix this, either move that logic to `useEffect` (if it isn't necessary for the first render), or delay showing that component until after the client renders (if the HTML looks broken until `useLayoutEffect` runs).
+>
+>To exclude a component that needs layout effects from the server-rendered HTML, render it conditionally with `showChild && ` and defer showing it with `useEffect(() => { setShowChild(true); }, [])`. This way, the UI doesn't appear broken before hydration.
### `useDebugValue` {#usedebugvalue}