From 0c96df0cd1f932000ec4b1a737a0c35b43c8eba9 Mon Sep 17 00:00:00 2001
From: Dan Abramov <dan.abramov@gmail.com>
Date: Thu, 29 Nov 2018 23:46:00 +0000
Subject: [PATCH] Add Suspense and lazy to API reference (#1446)

* Add Suspense and lazy to API reference

* Update content/docs/reference-react.md

Co-Authored-By: gaearon <dan.abramov@gmail.com>

* Simplify
---
 content/docs/reference-react.md | 48 +++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/content/docs/reference-react.md b/content/docs/reference-react.md
index b00bd559..8e83f3a8 100644
--- a/content/docs/reference-react.md
+++ b/content/docs/reference-react.md
@@ -58,6 +58,13 @@ See [Using React without JSX](/docs/react-without-jsx.html) for more information
 - [`React.createRef`](#reactcreateref)
 - [`React.forwardRef`](#reactforwardref)
 
+### Suspense
+
+Suspense lets components "wait" for something before rendering. Today, Suspense only supports one use case: [loading components dynamically with `React.lazy`](/docs/code-splitting.html#reactlazy). In the future, it will support other use cases like data fetching.
+
+- [`React.lazy`](#reactlazy)
+- [`React.Suspense`](#reactsuspense)
+
 * * *
 
 ## Reference
@@ -289,3 +296,44 @@ In the above example, React passes a `ref` given to `<FancyButton ref={ref}>` el
 As a result, after React attaches the ref, `ref.current` will point directly to the `<button>` DOM element instance.
 
 For more information, see [forwarding refs](/docs/forwarding-refs.html).
+
+### `React.lazy`
+
+`React.lazy()` lets you define a component that is loaded dynamically. This helps reduce the bundle size to delay loading components that aren't used during the initial render.
+
+You can learn how to use it from our [code splitting documentation](/docs/code-splitting.html#reactlazy). You might also want to check out [this article](https://medium.com/@pomber/lazy-loading-and-preloading-components-in-react-16-6-804de091c82d) explaining how to use it in more detail.
+
+```js
+// This component is loaded dynamically
+const SomeComponent = React.lazy(() => import('./SomeComponent'));
+```
+
+Note that rendering `lazy` components requires that there's a `<React.Suspense>` component higher in the rendering tree. This is how you specify a loading indicator.
+
+### `React.Suspense`
+
+`React.Suspense` let you specify the loading indicator in case some components in the tree below it are not yet ready to render. Today, lazy loading components is the **only** use case supported by `<React.Suspense>`:
+
+```js
+// This component is loaded dynamically
+const OtherComponent = React.lazy(() => import('./OtherComponent'));
+
+function MyComponent() {
+  return (
+    // Displays <Spinner> until OtherComponent loads
+    <React.Suspense fallback={<Spinner />}>
+      <div>
+        <OtherComponent />
+      </div>
+    </React.Suspense>
+  );
+}
+```
+
+It is documented in our [code splitting guide](/docs/code-splitting.html#reactlazy). Note that `lazy` components can be deep inside the `Suspense` tree -- it doesn't have to wrap every one of them. The best practice is to place `<Suspense>` where you want to see a loading indicator, but to use `lazy()` wherever you want to do code splitting.
+
+While this is not supported today, in the future we plan to let `Suspense` handle more scenarios such as data fetching. You can read about this in [our roadmap](/blog/2018/11/27/react-16-roadmap.html).
+
+>Note:
+>
+>`React.lazy()` and `<React.Suspense>` are not yet supported by `ReactDOMServer`. This is a known limitation that will be resolved in the future.