diff --git a/beta/src/content/reference/react/index.md b/beta/src/content/reference/react/index.md
index cf5f6fb2..1c280bb8 100644
--- a/beta/src/content/reference/react/index.md
+++ b/beta/src/content/reference/react/index.md
@@ -8,13 +8,11 @@ title: "react: Hooks"
-
-
---
## State Hooks {/*state-hooks*/}
-[State](/learn/state-a-components-memory) lets a component "remember" information like user input. For example, a form component can use state to store the input value, while an image gallery component can use state to store the selected image index.
+*State* lets a component ["remember" information like user input.](/learn/state-a-components-memory) For example, a form component can use state to store the input value, while an image gallery component can use state to store the selected image index.
To add state to a component, use one of these Hooks:
@@ -27,13 +25,11 @@ function ImageGallery() {
// ...
```
-[See the `useState` page for more examples.](/reference/react/useState)
-
---
## Context Hooks {/*context-hooks*/}
-[Context](/learn/passing-data-deeply-with-context) lets a component receive information from distant parents without [passing it as props.](/learn/passing-props-to-a-component) For example, your app's top-level component can pass the current UI theme to all components below, no matter how deep.
+*Context* lets a component [receive information from distant parents without passing it as props.](/learn/passing-props-to-a-component) For example, your app's top-level component can pass the current UI theme to all components below, no matter how deep.
* [`useContext`](/reference/react/useContext) reads and subscribes to a context.
@@ -43,13 +39,11 @@ function Button() {
// ...
```
-[See the `useContext` page for more examples.](/reference/react/useContext)
-
---
## Ref Hooks {/*ref-hooks*/}
-[Refs](/learn/referencing-values-with-refs) let a component hold some information that isn't used for rendering, like a DOM node or a timeout ID. Unlike with state, updating a ref does not re-render your component. Refs are an "escape hatch" from the React paradigm. They are useful when you need to work with non-React systems, such as the built-in browser APIs.
+*Refs* let a component [hold some information that isn't used for rendering,](/learn/referencing-values-with-refs) like a DOM node or a timeout ID. Unlike with state, updating a ref does not re-render your component. Refs are an "escape hatch" from the React paradigm. They are useful when you need to work with non-React systems, such as the built-in browser APIs.
* [`useRef`](/reference/react/useRef) declares a ref. You can hold any value in it, but most often it's used to hold a DOM node.
* [`useImperativeHandle`](/reference/react/useImperativeHandle) lets you customize the ref exposed by your component. This is rarely used.
@@ -60,13 +54,11 @@ function Form() {
// ...
```
-[See the `useRef` page for more examples.](/reference/react/useRef)
-
---
## Effect Hooks {/*effect-hooks*/}
-[Effects](/learn/synchronizing-with-effects) let a component connect to and synchronize with external systems. This includes dealing with network, browser DOM, animations, widgets written using a different UI library, and in general any non-React code.
+*Effects* let a component [connect to and synchronize with external systems.](/learn/synchronizing-with-effects) This includes dealing with network, browser DOM, animations, widgets written using a different UI library, and in general any non-React code.
* [`useEffect`](/reference/react/useEffect) connects a component to an external system.
@@ -80,17 +72,13 @@ function ChatRoom({ roomId }) {
// ...
```
-[See the `useEffect` page for more examples.](/reference/react/useEffect)
-
Effects are an "escape hatch" from the React paradigm. Don't use Effects to orchestrate the data flow of your application. If you're not interacting with an external system, [you might not need an Effect.](/learn/you-might-not-need-an-effect)
-There are two variations of `useEffect` with differences in timing:
+There are two rarely used variations of `useEffect` with differences in timing:
* [`useLayoutEffect`](/reference/react/useLayoutEffect) fires before the browser repaints the screen. You can measure layout here.
* [`useInsertionEffect`](/reference/react/useInsertionEffect) fires before React makes changes to the DOM. Libraries can insert dynamic CSS here.
-They are rarely used.
-
---
## Performance Hooks {/*performance-hooks*/}
@@ -109,8 +97,6 @@ function TodoList({ todos, tab, theme }) {
}
```
-[See the `useMemo` page for more examples.](/reference/react/useMemo)
-
Sometimes, you can't skip re-rendering because the screen actually needs to update. In that case, you can improve performance by separating blocking updates that must be synchronous (like typing into an input) from non-blocking updates which don't need to block the user interface (like updating a chart).
To prioritize rendering, use one of these Hooks:
diff --git a/beta/src/content/reference/react/memo.md b/beta/src/content/reference/react/memo.md
index f6f51b7f..75cc6175 100644
--- a/beta/src/content/reference/react/memo.md
+++ b/beta/src/content/reference/react/memo.md
@@ -20,16 +20,14 @@ const MemoizedComponent = memo(SomeComponent, arePropsEqual?)
### `memo(Component, arePropsEqual?)` {/*memo*/}
-Call `memo` outside of any components to define a memoized version of a component. This memoized component will usually not be re-rendered when its parent component is re-rendered as long as its props have not changed. But React may still re-render it: memoization is only a performance optimization, not a guarantee.
+Wrap a component in `memo` to get a *memoized* version of that component. This memoized version of your component will usually not be re-rendered when its parent component is re-rendered as long as its props have not changed. But React may still re-render it: memoization is only a performance optimization, not a guarantee.
```js
import { memo } from 'react';
-function SomeComponent(props) {
+const SomeComponent = memo(function SomeComponent(props) {
// ...
-}
-
-const MemoizedComponent = memo(SomeComponent);
+});
```
#### Parameters {/*parameters*/}
diff --git a/beta/src/content/reference/react/useCallback.md b/beta/src/content/reference/react/useCallback.md
index 38d9b467..de659d9c 100644
--- a/beta/src/content/reference/react/useCallback.md
+++ b/beta/src/content/reference/react/useCallback.md
@@ -20,7 +20,7 @@ const cachedFn = useCallback(fn, dependencies)
### `useCallback(fn, dependencies)` {/*usecallback*/}
-Call `useCallback` at the top level of your component to declare a memoized callback:
+Call `useCallback` at the top level of your component to cache a function definition between re-renders:
```js {4,9}
import { useCallback } from 'react';
@@ -38,7 +38,7 @@ export default function ProductPage({ productId, referrer, theme }) {
#### Parameters {/*parameters*/}
-* `fn`: The function value that you want to memoize. It can take any arguments and return any values. React will return (not call!) your function back to you during the initial render. On subsequent renders, React will return the same function again if the `dependencies` have not changed since the last render. Otherwise, it will give you the function that you have passed during the current render, and store it in case it can be reused later. React will not call the function. The function is returned to you so you can decide when and whether to call it.
+* `fn`: The function value that you want to cache. It can take any arguments and return any values. React will return (not call!) your function back to you during the initial render. On subsequent renders, React will give you the same function again if the `dependencies` have not changed since the last render. Otherwise, it will give you the function that you have passed during the current render, and store it in case it can be reused later. React will not call your function. The function is returned to you so you can decide when and whether to call it.
* `dependencies`: The list of all reactive values referenced inside of the `fn` code. Reactive values include props, state, and all the variables and functions declared directly inside your component body. If your linter is [configured for React](/learn/editor-setup#linting), it will verify that every reactive value is correctly specified as a dependency. The list of dependencies must have a constant number of items and be written inline like `[dep1, dep2, dep3]`. React will compare each dependency with its previous value using the [`Object.is`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is) comparison algorithm.
diff --git a/beta/src/content/reference/react/useMemo.md b/beta/src/content/reference/react/useMemo.md
index 19296e85..754e79da 100644
--- a/beta/src/content/reference/react/useMemo.md
+++ b/beta/src/content/reference/react/useMemo.md
@@ -20,7 +20,7 @@ const cachedValue = useMemo(calculateValue, dependencies)
### `useMemo(calculateValue, dependencies)` {/*usememo*/}
-Call `useMemo` at the top level of your component to declare a memoized value:
+Call `useMemo` at the top level of your component to cache a calculation between re-renders:
```js
import { useMemo } from 'react';
@@ -38,7 +38,7 @@ function TodoList({ todos, tab }) {
#### Parameters {/*parameters*/}
-* `calculateValue`: The function calculating the value that you want to memoize. It should be pure, should take no arguments, and should return a value of any type. React will call your function during the initial render. On subsequent renders, React will return the same value again if the `dependencies` have not changed since the last render. Otherwise, it will call `calculateValue`, return its result, and store it in case it can be reused later.
+* `calculateValue`: The function calculating the value that you want to cache. It should be pure, should take no arguments, and should return a value of any type. React will call your function during the initial render. On subsequent renders, React will return the same value again if the `dependencies` have not changed since the last render. Otherwise, it will call `calculateValue`, return its result, and store it in case it can be reused later.
* `dependencies`: The list of all reactive values referenced inside of the `calculateValue` code. Reactive values include props, state, and all the variables and functions declared directly inside your component body. If your linter is [configured for React](/learn/editor-setup#linting), it will verify that every reactive value is correctly specified as a dependency. The list of dependencies must have a constant number of items and be written inline like `[dep1, dep2, dep3]`. React will compare each dependency with its previous value using the [`Object.is`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is) comparison algorithm.
@@ -54,6 +54,12 @@ During subsequent renders, it will either return an already stored value from th
* In Strict Mode, React will **call your calculation function twice** in order to [help you find accidental impurities.](#my-calculation-runs-twice-on-every-re-render) This is development-only behavior and does not affect production. If your calculation function is pure (as it should be), this should not affect the logic of your component. The result from one of the calls will be ignored.
* React **will not throw away the cached value unless there is a specific reason to do that.** For example, in development, React throws away the cache when you edit the file of your component. Both in development and in production, React will throw away the cache if your component suspends during the initial mount. In the future, React may add more features that take advantage of throwing away the cache--for example, if React adds built-in support for virtualized lists in the future, it would make sense to throw away the cache for items that scroll out of the virtualized table viewport. This should match your expectations if you rely on `useMemo` solely as a performance optimization. Otherwise, a [state variable](/reference/react/useState#avoiding-recreating-the-initial-state) or a [ref](/reference/react/useRef#avoiding-recreating-the-ref-contents) may be more appropriate.
+
+
+Caching return values like this is also known as [*memoization*,](https://en.wikipedia.org/wiki/Memoization) which is why this Hook is called `useMemo`.
+
+
+
---
## Usage {/*usage*/}