Skip to content
This repository has been archived by the owner on Apr 21, 2023. It is now read-only.

Commit

Permalink
[Beta] Move Reference before Usage (#5399)
Browse files Browse the repository at this point in the history
* [Beta] Move Reference before Usage

* above -> below
  • Loading branch information
gaearon authored Dec 25, 2022
1 parent bd9f3ea commit 147bab9
Show file tree
Hide file tree
Showing 52 changed files with 4,493 additions and 4,512 deletions.
208 changes: 104 additions & 104 deletions beta/src/content/apis/react-dom/client/createRoot.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,110 @@ const root = createRoot(domNode, options?)
---
## Reference {/*reference*/}
### `createRoot(domNode, options?)` {/*createroot*/}
Call `createRoot` to create a React root for displaying content inside a browser DOM element.
```js
const domNode = document.getElementById('root');
const root = createRoot(domNode);
```
React will create a root for the `domNode`, and take over managing the DOM inside it. After you've created a root, you need to call [`root.render`](#root-render) to display a React component inside of it:
```js
root.render(<App />);
```
An app fully built with React will usually only have one `createRoot` call for its root component. A page that uses "sprinkles" of React for parts of the page may have as many separate roots as needed.
[See more examples below.](#usage)
#### Parameters {/*parameters*/}
* `domNode`: A [DOM element.](https://developer.mozilla.org/en-US/docs/Web/API/Element) React will create a root for this DOM element and allow you to call functions on the root, such as `render` to display rendered React content.
* **optional** `options`: An object with options for this React root.
* **optional** `onRecoverableError`: Callback called when React automatically recovers from errors.
* **optional** `identifierPrefix`: A string prefix React uses for IDs generated by [`useId`.](/apis/react/useId) Useful to avoid conflicts when using multiple roots on the same page.
#### Returns {/*returns*/}
`createRoot` returns an object with two methods: [`render`](#root-render) and [`unmount`.](#root-unmount)
#### Caveats {/*caveats*/}
* If your app is server-rendered, using `createRoot()` is not supported. Use [`hydrateRoot()`](/apis/react-dom/client/hydrateRoot) instead.
* You'll likely have only one `createRoot` call in your app. If you use a framework, it might do this call for you.
* When you want to render a piece of JSX in a different part of the DOM tree that isn't a child of your component (for example, a modal or a tooltip), use [`createPortal`](/apis/react-dom/createPortal) instead of `createRoot`.
---
### `root.render(reactNode)` {/*root-render*/}
Call `root.render` to display a piece of [JSX](/learn/writing-markup-with-jsx) ("React node") into the React root's browser DOM node.
```js
root.render(<App />);
```
React will display `<App />` in the `root`, and take over managing the DOM inside it.
[See more examples below.](#usage)
#### Parameters {/*root-render-parameters*/}
* `reactNode`: A *React node* that you want to display. This will usually be a piece of JSX like `<App />`, but you can also pass a React element constructed with [`createElement()`](/apis/react/createElement), a string, a number, `null`, or `undefined`.
#### Returns {/*root-render-returns*/}
`root.render` returns `undefined`.
#### Caveats {/*root-render-caveats*/}
* The first time you call `root.render`, React will clear all the existing HTML content inside the React root before rendering the React component into it.
* If your root's DOM node contains HTML generated by React on the server or during the build, use [`hydrateRoot()`](/apis/react-dom/client/hydrateRoot) instead, which attaches the event handlers to the existing HTML.
* If you call `render` on the same root more than once, React will update the DOM as necessary to reflect the latest JSX you passed. React will decide which parts of the DOM can be reused and which need to be recreated by ["matching it up"](/learn/preserving-and-resetting-state) with the previously rendered tree. Calling `render` on the same root again is similar to calling the [`set` function](/apis/react/useState#setstate) on the root component: React avoids unnecessary DOM updates.
---
### `root.unmount()` {/*root-unmount*/}
Call `root.unmount` to destroy a rendered tree inside a React root.
```js
root.unmount();
```
An app fully built with React will usually not have any calls to `root.unmount`.
This is mostly useful if your React root's DOM node (or any of its ancestors) may get removed from the DOM by some other code. For example, imagine a jQuery tab panel that removes inactive tabs from the DOM. If a tab gets removed, everything inside it (including the React roots inside) would get removed from the DOM as well. In that case, you need to tell React to "stop" managing the removed root's content by calling `root.unmount`. Otherwise, the components inside the removed root won't know to clean up and free up global resources like subscriptions.
Calling `root.unmount` will unmount all the components in the root and "detach" React from the root DOM node, including removing any event handlers or state in the tree.
#### Parameters {/*root-unmount-parameters*/}
`root.unmount` does not accept any parameters.
#### Returns {/*root-unmount-returns*/}
`root.unmount` returns `undefined`.
#### Caveats {/*root-unmount-caveats*/}
* Calling `root.unmount` will unmount all the components in the tree and "detach" React from the root DOM node.
* Once you call `root.unmount` you cannot call `root.render` again on the same root. Attempting to call `root.render` on an unmounted root will throw a "Cannot update an unmounted root" error. However, you can create a new root for the same DOM node after the previous root for that node has been unmounted.
---
## Usage {/*usage*/}
### Rendering an app fully built with React {/*rendering-an-app-fully-built-with-react*/}
Expand Down Expand Up @@ -231,110 +335,6 @@ export default function App({counter}) {
It is uncommon to call `render` multiple times. Usually, you'll [update state](/apis/react/useState) inside one of the components instead.

---
## Reference {/*reference*/}

### `createRoot(domNode, options?)` {/*createroot*/}

Call `createRoot` to create a React root for displaying content inside a browser DOM element.

```js
const domNode = document.getElementById('root');
const root = createRoot(domNode);
```

React will create a root for the `domNode`, and take over managing the DOM inside it. After you've created a root, you need to call [`root.render`](#root-render) to display a React component inside of it:
```js
root.render(<App />);
```
An app fully built with React will usually only have one `createRoot` call for its root component. A page that uses "sprinkles" of React for parts of the page may have as many separate roots as needed.
[See examples above.](#usage)
#### Parameters {/*parameters*/}
* `domNode`: A [DOM element.](https://developer.mozilla.org/en-US/docs/Web/API/Element) React will create a root for this DOM element and allow you to call functions on the root, such as `render` to display rendered React content.
* **optional** `options`: An object with options for this React root.
* **optional** `onRecoverableError`: Callback called when React automatically recovers from errors.
* **optional** `identifierPrefix`: A string prefix React uses for IDs generated by [`useId`.](/apis/react/useId) Useful to avoid conflicts when using multiple roots on the same page.
#### Returns {/*returns*/}
`createRoot` returns an object with two methods: [`render`](#root-render) and [`unmount`.](#root-unmount)
#### Caveats {/*caveats*/}
* If your app is server-rendered, using `createRoot()` is not supported. Use [`hydrateRoot()`](/apis/react-dom/client/hydrateRoot) instead.
* You'll likely have only one `createRoot` call in your app. If you use a framework, it might do this call for you.
* When you want to render a piece of JSX in a different part of the DOM tree that isn't a child of your component (for example, a modal or a tooltip), use [`createPortal`](/apis/react-dom/createPortal) instead of `createRoot`.
---
### `root.render(reactNode)` {/*root-render*/}
Call `root.render` to display a piece of [JSX](/learn/writing-markup-with-jsx) ("React node") into the React root's browser DOM node.

```js
root.render(<App />);
```

React will display `<App />` in the `root`, and take over managing the DOM inside it.

[See examples above.](#usage)

#### Parameters {/*root-render-parameters*/}

* `reactNode`: A *React node* that you want to display. This will usually be a piece of JSX like `<App />`, but you can also pass a React element constructed with [`createElement()`](/apis/react/createElement), a string, a number, `null`, or `undefined`.


#### Returns {/*root-render-returns*/}

`root.render` returns `undefined`.

#### Caveats {/*root-render-caveats*/}

* The first time you call `root.render`, React will clear all the existing HTML content inside the React root before rendering the React component into it.

* If your root's DOM node contains HTML generated by React on the server or during the build, use [`hydrateRoot()`](/apis/react-dom/client/hydrateRoot) instead, which attaches the event handlers to the existing HTML.
* If you call `render` on the same root more than once, React will update the DOM as necessary to reflect the latest JSX you passed. React will decide which parts of the DOM can be reused and which need to be recreated by ["matching it up"](/learn/preserving-and-resetting-state) with the previously rendered tree. Calling `render` on the same root again is similar to calling the [`set` function](/apis/react/useState#setstate) on the root component: React avoids unnecessary DOM updates.
---
### `root.unmount()` {/*root-unmount*/}
Call `root.unmount` to destroy a rendered tree inside a React root.
```js
root.unmount();
```
An app fully built with React will usually not have any calls to `root.unmount`.
This is mostly useful if your React root's DOM node (or any of its ancestors) may get removed from the DOM by some other code. For example, imagine a jQuery tab panel that removes inactive tabs from the DOM. If a tab gets removed, everything inside it (including the React roots inside) would get removed from the DOM as well. In that case, you need to tell React to "stop" managing the removed root's content by calling `root.unmount`. Otherwise, the components inside the removed root won't know to clean up and free up global resources like subscriptions.

Calling `root.unmount` will unmount all the components in the root and "detach" React from the root DOM node, including removing any event handlers or state in the tree.


#### Parameters {/*root-unmount-parameters*/}

`root.unmount` does not accept any parameters.


#### Returns {/*root-unmount-returns*/}

`root.unmount` returns `undefined`.

#### Caveats {/*root-unmount-caveats*/}

* Calling `root.unmount` will unmount all the components in the tree and "detach" React from the root DOM node.

* Once you call `root.unmount` you cannot call `root.render` again on the same root. Attempting to call `root.render` on an unmounted root will throw a "Cannot update an unmounted root" error. However, you can create a new root for the same DOM node after the previous root for that node has been unmounted.

---

## Troubleshooting {/*troubleshooting*/}

### I've created a root, but nothing is displayed {/*ive-created-a-root-but-nothing-is-displayed*/}
Expand Down
Loading

0 comments on commit 147bab9

Please sign in to comment.