Browse Source

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
main
Dan Abramov 6 years ago
committed by GitHub
parent
commit
0c96df0cd1
No known key found for this signature in database GPG Key ID: 4AEE18F83AFDEB23
  1. 48
      content/docs/reference-react.md

48
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.

Loading…
Cancel
Save