Browse Source
* Add ReactDOM Client APIs * Feedback fixes * TODO and link fixes * Update createRoot.md * Nits * Nits * Update reactdomclient.md * Update hydrateRoot.md * Update hydrateRoot.md * Update createRoot.md * Update hydrateRoot.md * createRoot tweaks * bla * tweaks * tweaks * tweak * bump * Add another troubleshooting error * Add stubs for React.* APIs * Add and organize remaining APIs * Update links * fix whitespace * Add re-directs for old API URLs * Fix some links * Add StrictMode Co-authored-by: dan <dan.abramov@gmail.com>main
Ricky
3 years ago
committed by
GitHub
GitHub
73 changed files with 1714 additions and 272 deletions
@ -1,102 +0,0 @@ |
|||
--- |
|||
title: React APIs |
|||
--- |
|||
|
|||
<Intro> |
|||
|
|||
The React package contains all the APIs necessary to define and use [components](/learn/your-first-component). |
|||
|
|||
</Intro> |
|||
|
|||
## Installation {/*installation*/} |
|||
|
|||
It is available as [`react`](https://www.npmjs.com/package/react) on npm. You can also [add React to the page as a `<script>` tag](/learn/add-react-to-a-website). |
|||
|
|||
<PackageImport> |
|||
|
|||
<TerminalBlock> |
|||
|
|||
npm install react |
|||
|
|||
</TerminalBlock> |
|||
|
|||
```js |
|||
// Importing a specific API: |
|||
import { useState } from 'react'; |
|||
|
|||
// Importing all APIs together: |
|||
import * as React from 'react'; |
|||
``` |
|||
|
|||
</PackageImport> |
|||
|
|||
If you use React on the web, you'll also need the same version of [ReactDOM](/apis/reactdom). |
|||
|
|||
## Exports {/*exports*/} |
|||
|
|||
### State {/*state*/} |
|||
|
|||
<YouWillLearnCard title="useState" path="/apis/usestate"> |
|||
|
|||
Declares a state variable. |
|||
|
|||
```js |
|||
function MyComponent() { |
|||
const [age, setAge] = useState(42); |
|||
// ... |
|||
``` |
|||
|
|||
</YouWillLearnCard> |
|||
|
|||
<YouWillLearnCard title="useReducer" path="/apis/usereducer"> |
|||
|
|||
Declares a state variable managed with a reducer. |
|||
|
|||
```js |
|||
function MyComponent() { |
|||
const [state, dispatch] = useReducer(reducer, { age: 42 }); |
|||
// ... |
|||
``` |
|||
|
|||
</YouWillLearnCard> |
|||
|
|||
### Context {/*context*/} |
|||
|
|||
<YouWillLearnCard title="useContext" path="/apis/usecontext"> |
|||
|
|||
Reads and subscribes to a context. |
|||
|
|||
```js |
|||
function MyComponent() { |
|||
const theme = useContext(ThemeContext); |
|||
// ... |
|||
``` |
|||
|
|||
</YouWillLearnCard> |
|||
|
|||
<YouWillLearnCard title="createContext" path="/apis/createContext"> |
|||
|
|||
Creates a context that components can provide or read. |
|||
|
|||
```js |
|||
const ThemeContext = createContext('light'); |
|||
``` |
|||
|
|||
</YouWillLearnCard> |
|||
|
|||
### Refs {/*refs*/} |
|||
|
|||
<YouWillLearnCard title="useRef" path="/apis/useref"> |
|||
|
|||
Declares a ref. |
|||
|
|||
```js |
|||
function MyComponent() { |
|||
const inputRef = useRef(null); |
|||
// ... |
|||
``` |
|||
|
|||
</YouWillLearnCard> |
|||
|
|||
|
|||
This section is incomplete and is still being written! |
|||
@ -0,0 +1,21 @@ |
|||
--- |
|||
title: createPortal |
|||
--- |
|||
|
|||
<Wip> |
|||
|
|||
This section is incomplete, please see the old docs for [createPortal](https://reactjs.org/docs/react-dom.html#createportal). |
|||
|
|||
</Wip> |
|||
|
|||
|
|||
<Intro> |
|||
|
|||
Portals provide a way to render children into a DOM node that exists outside the hierarchy of the DOM component. |
|||
|
|||
|
|||
```js |
|||
createPortal(child, container) |
|||
``` |
|||
|
|||
</Intro> |
|||
@ -0,0 +1,26 @@ |
|||
--- |
|||
title: findDOMNode |
|||
--- |
|||
|
|||
<Wip> |
|||
|
|||
This section is incomplete, please see the old docs for [findDOMNode](https://reactjs.org/docs/react-dom.html#finddomnode). |
|||
|
|||
</Wip> |
|||
|
|||
|
|||
<Intro> |
|||
|
|||
If this component has been mounted into the DOM, this returns the corresponding native browser DOM element. This method is useful for reading values out of the DOM, such as form field values and performing DOM measurements. **In most cases, you can attach a ref to the DOM node and avoid using findDOMNode at all.** |
|||
|
|||
```js |
|||
findDOMNode(component) |
|||
``` |
|||
|
|||
</Intro> |
|||
|
|||
<Gotcha> |
|||
|
|||
`findDOMNode` is an escape hatch used to access the underlying DOM node. In most cases, use of this escape hatch is discouraged because it pierces the component abstraction. [It has been deprecated in StrictMode](https://reactjs.org/docs/strict-mode.html#warning-about-deprecated-finddomnode-usage). |
|||
|
|||
</Gotcha> |
|||
@ -0,0 +1,21 @@ |
|||
--- |
|||
title: flushSync |
|||
--- |
|||
|
|||
<Wip> |
|||
|
|||
This section is incomplete, please see the old docs for [flushSync](https://reactjs.org/docs/react-dom.html#flushsync). |
|||
|
|||
</Wip> |
|||
|
|||
|
|||
<Intro> |
|||
|
|||
Force React to flush any updates inside the provided callback synchronously. This ensures that the DOM is updated immediately. |
|||
|
|||
|
|||
```js |
|||
flushSync(callback) |
|||
``` |
|||
|
|||
</Intro> |
|||
@ -0,0 +1,20 @@ |
|||
--- |
|||
title: flushSync |
|||
--- |
|||
|
|||
<Wip> |
|||
|
|||
This section is incomplete, please see the old docs for [hydrate](https://reactjs.org/docs/react-dom.html#hydrate). |
|||
|
|||
</Wip> |
|||
|
|||
|
|||
<Intro> |
|||
|
|||
Same as `render()`, but is used to hydrate a container whose HTML contents were rendered by `react-dom/server`. React will attempt to attach event listeners to the existing markup. |
|||
|
|||
```js |
|||
hydrate(element, container, callback?) |
|||
``` |
|||
|
|||
</Intro> |
|||
@ -0,0 +1,181 @@ |
|||
--- |
|||
title: ReactDOM APIs |
|||
--- |
|||
|
|||
<Wip> |
|||
|
|||
This section is incomplete, please see the old docs for [ReactDOM](https://reactjs.org/docs/react-dom.html). |
|||
|
|||
</Wip> |
|||
|
|||
|
|||
<Intro> |
|||
|
|||
The ReactDOM package lets you render React components on a webpage. |
|||
|
|||
</Intro> |
|||
|
|||
Typically, you will use ReactDOM at the top level of your app to display your components. You will either use it directly or a [framework](/learn/start-a-new-react-project#building-with-react-and-a-framework) may do it for you. Most of your components should *not* need to import this module. |
|||
|
|||
## Installation {/*installation*/} |
|||
|
|||
<PackageImport> |
|||
|
|||
<TerminalBlock> |
|||
|
|||
npm install react-dom |
|||
|
|||
</TerminalBlock> |
|||
|
|||
```js |
|||
// Importing a specific API: |
|||
import { createRoot } from 'react-dom/client'; |
|||
|
|||
// Importing all APIs together: |
|||
import * as ReactDOMClient from 'react-dom/client'; |
|||
``` |
|||
|
|||
</PackageImport> |
|||
|
|||
You'll also need to install the same version of [React](/apis/react). |
|||
|
|||
## Browser Support {/*browser-support*/} |
|||
|
|||
ReactDOM supports all popular browsers, including Internet Explorer 9 and above. [Some polyfills are required](http://todo%20link%20to%20js%20environment%20requirements/) for older browsers such as IE 9 and IE 10. |
|||
|
|||
## Exports {/*exports*/} |
|||
|
|||
### Portals {/*portals*/} |
|||
|
|||
<YouWillLearnCard title="createPortal" path="/apis/react-dom/createPortal"> |
|||
|
|||
Create a portal. |
|||
|
|||
```js |
|||
createPortal(child, container); |
|||
``` |
|||
|
|||
</YouWillLearnCard> |
|||
|
|||
### Flushing {/*flushing*/} |
|||
|
|||
<YouWillLearnCard title="flushSync" path="/apis/react-dom/flushSync"> |
|||
|
|||
Flush in progress updates. |
|||
|
|||
```js |
|||
flushSync(() => { |
|||
// ... |
|||
}); |
|||
``` |
|||
|
|||
</YouWillLearnCard> |
|||
|
|||
### Client APIs {/*clientapis*/} |
|||
|
|||
<YouWillLearnCard title="createRoot" path="/apis/react-dom/client/createRoot"> |
|||
|
|||
Create and render a React root. |
|||
|
|||
```js |
|||
const root = createRoot(domNode); |
|||
root.render(<App />); |
|||
``` |
|||
|
|||
</YouWillLearnCard> |
|||
|
|||
<YouWillLearnCard title="hydrateRoot" path="/apis/react-dom/client/hydrateRoot"> |
|||
|
|||
Hydrate server-rendered HTML. |
|||
|
|||
```js |
|||
hydrateRoot(domNode, <App />); |
|||
``` |
|||
|
|||
</YouWillLearnCard> |
|||
|
|||
### Server APIs {/*serverapis*/} |
|||
|
|||
<YouWillLearnCard title="renderToPipeableStream" path="/apis/react-dom/server/renderToPipeableStream"> |
|||
|
|||
Render a React element to a pipeable stream. |
|||
|
|||
```js |
|||
renderToPipeableStream(element, options) |
|||
``` |
|||
|
|||
</YouWillLearnCard> |
|||
|
|||
<YouWillLearnCard title="renderToReadableStream" path="/apis/react-dom/server/renderToReadableStream"> |
|||
|
|||
Render a React element to a Readable stream. |
|||
|
|||
```js |
|||
renderToReadableStream(element, options) |
|||
``` |
|||
|
|||
</YouWillLearnCard> |
|||
|
|||
<YouWillLearnCard title="renderToNodeStream" path="/apis/react-dom/server/renderToNodeStream"> |
|||
|
|||
Render a React element to a Node stream. |
|||
|
|||
```js |
|||
renderToNodeStream(element) |
|||
``` |
|||
|
|||
</YouWillLearnCard> |
|||
|
|||
<YouWillLearnCard title="renderToStaticNodeStream" path="/apis/react-dom/server/renderToStaticNodeStream"> |
|||
|
|||
Render a React element to a static Node stream. |
|||
|
|||
```js |
|||
renderToStaticNodeStream(element) |
|||
``` |
|||
|
|||
</YouWillLearnCard> |
|||
|
|||
<YouWillLearnCard title="renderToString" path="/apis/react-dom/server/renderToString"> |
|||
|
|||
Render a React element to a string. |
|||
|
|||
```js |
|||
renderToString(element) |
|||
``` |
|||
|
|||
</YouWillLearnCard> |
|||
|
|||
<YouWillLearnCard title="renderToStaticMarkup" path="/apis/react-dom/server/renderToStaticMarkup"> |
|||
|
|||
Render a React element to static markup. |
|||
|
|||
```js |
|||
renderToStaticMarkup(element) |
|||
``` |
|||
|
|||
</YouWillLearnCard> |
|||
|
|||
### Deprecated {/*deprecated*/} |
|||
|
|||
<YouWillLearnCard title="render" path="/apis/react-dom/render"> |
|||
|
|||
Displays a React component inside a browser DOM node (deprecated). |
|||
|
|||
```js |
|||
render(<App />, document.getElementById('root')); |
|||
``` |
|||
|
|||
</YouWillLearnCard> |
|||
|
|||
<YouWillLearnCard title="hydrate" path="/apis/react-dom/hydrate"> |
|||
|
|||
Hydrate server-rendered HTMl (deprecated). |
|||
|
|||
```js |
|||
hydrate(<App />, document.getElementById('root')); |
|||
``` |
|||
|
|||
</YouWillLearnCard> |
|||
|
|||
This section is incomplete and is still being written! |
|||
@ -0,0 +1,21 @@ |
|||
--- |
|||
title: renderToNodeStream |
|||
--- |
|||
|
|||
<Wip> |
|||
|
|||
This section is incomplete, please see the old docs for [renderToNodeStream](https://reactjs.org/docs/react-dom-server.html#rendertonodestream). |
|||
|
|||
</Wip> |
|||
|
|||
|
|||
<Intro> |
|||
|
|||
Render a React element to its initial HTML. |
|||
|
|||
|
|||
```js |
|||
renderToNodeStream(element) |
|||
``` |
|||
|
|||
</Intro> |
|||
@ -0,0 +1,21 @@ |
|||
--- |
|||
title: renderToPipeableStream |
|||
--- |
|||
|
|||
<Wip> |
|||
|
|||
This section is incomplete, please see the old docs for [renderToPipeableStream](https://reactjs.org/docs/react-dom-server.html#rendertopipeablestream). |
|||
|
|||
</Wip> |
|||
|
|||
|
|||
<Intro> |
|||
|
|||
Render a React element to a stream. |
|||
|
|||
|
|||
```js |
|||
renderToPipeableStream(element, options) |
|||
``` |
|||
|
|||
</Intro> |
|||
@ -0,0 +1,21 @@ |
|||
--- |
|||
title: renderToReadableStream |
|||
--- |
|||
|
|||
<Wip> |
|||
|
|||
This section is incomplete, please see the old docs for [renderToReadableStream](https://reactjs.org/docs/react-dom-server.html#rendertoreadablestream). |
|||
|
|||
</Wip> |
|||
|
|||
|
|||
<Intro> |
|||
|
|||
Streams a React element to its initial HTML. Returns a Promise that resolves to a [Readable Stream](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream). Fully supports Suspense and streaming of HTML. [Read more](https://github.com/reactwg/react-18/discussions/127) |
|||
|
|||
|
|||
```js |
|||
renderToReadableStream(element, options); |
|||
``` |
|||
|
|||
</Intro> |
|||
@ -0,0 +1,23 @@ |
|||
--- |
|||
title: renderToStaticMarkup |
|||
--- |
|||
|
|||
<Wip> |
|||
|
|||
This section is incomplete, please see the old docs for [renderToStaticMarkup](https://reactjs.org/docs/react-dom-server.html#rendertostaticmarkup). |
|||
|
|||
</Wip> |
|||
|
|||
|
|||
<Intro> |
|||
|
|||
Similar to renderToString, except this doesn’t create extra DOM attributes that React uses internally, such as data-reactroot. This is useful if you want to use React as a simple static page generator, as stripping away the extra attributes can save some bytes. |
|||
|
|||
|
|||
```js |
|||
renderToStaticMarkup(element) |
|||
``` |
|||
|
|||
If you plan to use React on the client to make the markup interactive, do not use this method. Instead, use renderToString on the server and ReactDOM.hydrateRoot() on the client. |
|||
|
|||
</Intro> |
|||
@ -0,0 +1,21 @@ |
|||
--- |
|||
title: renderToStaticNodeStream |
|||
--- |
|||
|
|||
<Wip> |
|||
|
|||
This section is incomplete, please see the old docs for [renderToStaticNodeStream](https://reactjs.org/docs/react-dom-server.html#rendertostaticnodestream). |
|||
|
|||
</Wip> |
|||
|
|||
|
|||
<Intro> |
|||
|
|||
Similar to renderToNodeStream, except this doesn’t create extra DOM attributes that React uses internally, such as `data-reactroot`. This is useful if you want to use React as a simple static page generator, as stripping away the extra attributes can save some bytes. |
|||
|
|||
|
|||
```js |
|||
renderToStaticNodeStream(element) |
|||
``` |
|||
|
|||
</Intro> |
|||
@ -0,0 +1,21 @@ |
|||
--- |
|||
title: renderToString |
|||
--- |
|||
|
|||
<Wip> |
|||
|
|||
This section is incomplete, please see the old docs for [renderToString](https://reactjs.org/docs/react-dom-server.html#rendertostring). |
|||
|
|||
</Wip> |
|||
|
|||
|
|||
<Intro> |
|||
|
|||
Render a React element to its initial HTML. React will return an HTML string. You can use this method to generate HTML on the server and send the markup down on the initial request for faster page loads and to allow search engines to crawl your pages for SEO purposes. |
|||
|
|||
|
|||
```js |
|||
renderToString(element) |
|||
``` |
|||
|
|||
</Intro> |
|||
@ -0,0 +1,20 @@ |
|||
--- |
|||
title: unmountComponentAtNode |
|||
--- |
|||
|
|||
<Wip> |
|||
|
|||
This section is incomplete, please see the old docs for [unmountComponentAtNode](https://reactjs.org/docs/react-dom.html#unmountcomponentatnode). |
|||
|
|||
</Wip> |
|||
|
|||
|
|||
<Intro> |
|||
|
|||
Remove a mounted React component from the DOM and clean up its event handlers and state. If no component was mounted in the container, calling this function does nothing. Returns `true` if a component was unmounted and `false` if there was no component to unmount. |
|||
|
|||
```js |
|||
unmountComponentAtNode(container) |
|||
``` |
|||
|
|||
</Intro> |
|||
@ -0,0 +1,18 @@ |
|||
--- |
|||
title: React.Children |
|||
--- |
|||
|
|||
<Wip> |
|||
|
|||
This section is incomplete, please see the old docs for [React.Children](https://reactjs.org/docs/react-api.html#reactchildren). |
|||
|
|||
</Wip> |
|||
|
|||
|
|||
<Intro> |
|||
|
|||
`React.Children` provides utilities for dealing with the this.props.children opaque data structure. |
|||
|
|||
See the [React.Children](https://reactjs.org/docs/react-api.html#reactchildren) docs for more info. |
|||
|
|||
</Intro> |
|||
@ -0,0 +1,26 @@ |
|||
--- |
|||
title: React.Component |
|||
--- |
|||
|
|||
<Wip> |
|||
|
|||
This section is incomplete, please see the old docs for [React.Component](https://reactjs.org/docs/react-component.html). |
|||
|
|||
</Wip> |
|||
|
|||
|
|||
<Intro> |
|||
|
|||
React lets you define components as classes: |
|||
|
|||
```js |
|||
class Welcome extends React.Component { |
|||
render() { |
|||
return <h1>Hello, {this.props.name}</h1>; |
|||
} |
|||
} |
|||
``` |
|||
|
|||
The only method you must define in a `React.Component` subclass is called `render()`. All the other methods described on are optional. Please see the old [React.Component](https://reactjs.org/docs/react-component.html) docs for more info. |
|||
|
|||
</Intro> |
|||
@ -0,0 +1,31 @@ |
|||
--- |
|||
title: React.Fragment |
|||
--- |
|||
|
|||
<Wip> |
|||
|
|||
This section is incomplete, please see the old docs for [React.Fragment](https://reactjs.org/docs/react-api.html#reactfragment). |
|||
|
|||
</Wip> |
|||
|
|||
|
|||
<Intro> |
|||
|
|||
The `React.Fragment` component lets you return multiple elements without creating an additional DOM element: |
|||
|
|||
``` |
|||
function Component() { |
|||
return ( |
|||
<React.Fragment> |
|||
Some text. |
|||
<h2>A heading</h2> |
|||
</React.Fragment> |
|||
); |
|||
} |
|||
``` |
|||
|
|||
You can also use it with the shorthand `<></>` syntax. |
|||
|
|||
For more information, see [React v16.2.0: Improved Support for Fragments](https://reactjs.org/blog/2017/11/28/react-v16.2.0-fragment-support.html). |
|||
|
|||
</Intro> |
|||
@ -0,0 +1,26 @@ |
|||
--- |
|||
title: React.PureComponent |
|||
--- |
|||
|
|||
<Wip> |
|||
|
|||
This section is incomplete, please see the old docs for [React.PureComponent](https://reactjs.org/docs/react-api.html#reactpurecomponent). |
|||
|
|||
</Wip> |
|||
|
|||
|
|||
<Intro> |
|||
|
|||
React.PureComponent is similar to React.Component. The difference between them is that React.Component doesn’t implement shouldComponentUpdate(), but React.PureComponent implements it with a shallow prop and state comparison. |
|||
|
|||
If your React component’s render() function renders the same result given the same props and state, you can use React.PureComponent for a performance boost in some cases. |
|||
|
|||
```js |
|||
class Welcome extends React.PureComponent { |
|||
render() { |
|||
return <h1>Hello, {this.props.name}</h1>; |
|||
} |
|||
} |
|||
``` |
|||
|
|||
</Intro> |
|||
@ -0,0 +1,10 @@ |
|||
--- |
|||
title: StrictMode |
|||
--- |
|||
|
|||
<Wip> |
|||
|
|||
This section is incomplete, please see the old docs for [StrictMode](https://reactjs.org/docs/strict-mode.html). |
|||
|
|||
</Wip> |
|||
|
|||
@ -0,0 +1,18 @@ |
|||
--- |
|||
title: Suspense |
|||
--- |
|||
|
|||
<Wip> |
|||
|
|||
This section is incomplete, please see the old docs for [Suspense](https://reactjs.org/docs/react-api.html#reactsuspense). |
|||
|
|||
</Wip> |
|||
|
|||
|
|||
<Intro> |
|||
|
|||
```js |
|||
<React.Suspense fallback={<Spinner />}> |
|||
``` |
|||
|
|||
</Intro> |
|||
@ -0,0 +1,18 @@ |
|||
--- |
|||
title: cloneElement |
|||
--- |
|||
|
|||
<Wip> |
|||
|
|||
This section is incomplete, please see the old docs for [cloneElement](https://reactjs.org/docs/react-api.html#cloneelement). |
|||
|
|||
</Wip> |
|||
|
|||
|
|||
<Intro> |
|||
|
|||
```js |
|||
React.cloneElement(element, [config], [...children]) |
|||
``` |
|||
|
|||
</Intro> |
|||
@ -0,0 +1,18 @@ |
|||
--- |
|||
title: createElement |
|||
--- |
|||
|
|||
<Wip> |
|||
|
|||
This section is incomplete, please see the old docs for [createElement](https://reactjs.org/docs/react-api.html#createelement). |
|||
|
|||
</Wip> |
|||
|
|||
|
|||
<Intro> |
|||
|
|||
```js |
|||
React.createElement(type, [props], [...children]) |
|||
``` |
|||
|
|||
</Intro> |
|||
@ -0,0 +1,18 @@ |
|||
--- |
|||
title: createFactory |
|||
--- |
|||
|
|||
<Wip> |
|||
|
|||
This section is incomplete, please see the old docs for [createFactory](https://reactjs.org/docs/react-api.html#createfactory). |
|||
|
|||
</Wip> |
|||
|
|||
|
|||
<Intro> |
|||
|
|||
```js |
|||
React.createFactory(type) |
|||
``` |
|||
|
|||
</Intro> |
|||
@ -0,0 +1,18 @@ |
|||
--- |
|||
title: createRef |
|||
--- |
|||
|
|||
<Wip> |
|||
|
|||
This section is incomplete, please see the old docs for [createRef](https://reactjs.org/docs/react-api.html#reactcreateref). |
|||
|
|||
</Wip> |
|||
|
|||
|
|||
<Intro> |
|||
|
|||
```js |
|||
React.createRef(); |
|||
``` |
|||
|
|||
</Intro> |
|||
@ -0,0 +1,24 @@ |
|||
--- |
|||
title: forwardRef |
|||
--- |
|||
|
|||
<Wip> |
|||
|
|||
This section is incomplete, please see the old docs for [forwardRef](https://reactjs.org/docs/react-api.html#reactforwardref). |
|||
|
|||
</Wip> |
|||
|
|||
|
|||
<Intro> |
|||
|
|||
`React.forwardRef` creates a React component that forwards the `ref` attribute it receives to another component below in the tree. |
|||
|
|||
```js |
|||
const FancyButton = React.forwardRef((props, ref) => ( |
|||
<button ref={ref} className="FancyButton"> |
|||
{props.children} |
|||
</button> |
|||
)); |
|||
``` |
|||
|
|||
</Intro> |
|||
@ -0,0 +1,427 @@ |
|||
--- |
|||
title: React APIs |
|||
--- |
|||
|
|||
<Wip> |
|||
|
|||
This section is incomplete, please see the old docs for [React](https://reactjs.org/docs/react-api.html). |
|||
|
|||
</Wip> |
|||
|
|||
<Intro> |
|||
|
|||
The React package contains all the APIs necessary to define and use [components](/learn/your-first-component). |
|||
|
|||
</Intro> |
|||
|
|||
## Installation {/*installation*/} |
|||
|
|||
It is available as [`react`](https://www.npmjs.com/package/react) on npm. You can also [add React to the page as a `<script>` tag](/learn/add-react-to-a-website). |
|||
|
|||
<PackageImport> |
|||
|
|||
<TerminalBlock> |
|||
|
|||
npm install react |
|||
|
|||
</TerminalBlock> |
|||
|
|||
```js |
|||
// Importing a specific API: |
|||
import { useState } from 'react'; |
|||
|
|||
// Importing all APIs together: |
|||
import * as React from 'react'; |
|||
``` |
|||
|
|||
</PackageImport> |
|||
|
|||
If you use React on the web, you'll also need the same version of [ReactDOM](/apis/react-dom). |
|||
|
|||
## Exports {/*exports*/} |
|||
|
|||
### State {/*state*/} |
|||
|
|||
<YouWillLearnCard title="useState" path="/apis/react/useState"> |
|||
|
|||
Declares a state variable. |
|||
|
|||
```js |
|||
function MyComponent() { |
|||
const [age, setAge] = useState(42); |
|||
// ... |
|||
``` |
|||
|
|||
</YouWillLearnCard> |
|||
|
|||
<YouWillLearnCard title="useReducer" path="/apis/react/useReducer"> |
|||
|
|||
Declares a state variable managed with a reducer. |
|||
|
|||
```js |
|||
function MyComponent() { |
|||
const [state, dispatch] = useReducer(reducer, { age: 42 }); |
|||
// ... |
|||
``` |
|||
|
|||
</YouWillLearnCard> |
|||
|
|||
### Context {/*context*/} |
|||
|
|||
<YouWillLearnCard title="useContext" path="/apis/react/useContext"> |
|||
|
|||
Reads and subscribes to a context. |
|||
|
|||
```js |
|||
function MyComponent() { |
|||
const theme = useContext(ThemeContext); |
|||
// ... |
|||
``` |
|||
|
|||
</YouWillLearnCard> |
|||
|
|||
<YouWillLearnCard title="createContext" path="/apis/react/useContext"> |
|||
|
|||
Creates a context that components can provide or read. |
|||
|
|||
```js |
|||
const ThemeContext = createContext('light'); |
|||
``` |
|||
|
|||
</YouWillLearnCard> |
|||
|
|||
### Refs {/*refs*/} |
|||
|
|||
|
|||
<YouWillLearnCard title="useRef" path="/apis/react/useRef"> |
|||
|
|||
Declares a ref. |
|||
|
|||
```js |
|||
function MyComponent() { |
|||
const inputRef = useRef(null); |
|||
// ... |
|||
``` |
|||
|
|||
</YouWillLearnCard> |
|||
|
|||
<YouWillLearnCard title="forwardRef" path="/apis/react/forwardRef"> |
|||
|
|||
Create a component that forward the ref attribute: |
|||
|
|||
```js |
|||
const Component = forwardRef((props, ref) => { |
|||
// ... |
|||
}); |
|||
``` |
|||
|
|||
</YouWillLearnCard> |
|||
|
|||
<YouWillLearnCard title="useImperativeHandle" path="/apis/react/useImperativeHandle"> |
|||
|
|||
Customize instance value exposed to parent refs: |
|||
|
|||
```js |
|||
useImperativeHandle(ref, () => { |
|||
// ... |
|||
}); |
|||
``` |
|||
|
|||
</YouWillLearnCard> |
|||
|
|||
<YouWillLearnCard title="createRef" path="/apis/react/createRef"> |
|||
|
|||
Create a ref (typically for class components): |
|||
|
|||
```js |
|||
this.ref = createRef(); |
|||
``` |
|||
|
|||
</YouWillLearnCard> |
|||
|
|||
### Components {/*components*/} |
|||
|
|||
<YouWillLearnCard title="React.Component" path="/apis/react/Component"> |
|||
|
|||
Define a components as a class: |
|||
|
|||
```js |
|||
class MyComponent extends React.Component { |
|||
// ... |
|||
} |
|||
``` |
|||
|
|||
</YouWillLearnCard> |
|||
|
|||
<YouWillLearnCard title="React.PureComponent" path="/apis/react/PureComponent"> |
|||
|
|||
Define a pure component as a class: |
|||
|
|||
```js |
|||
class MyComponent extends React.PureComponent { |
|||
// ... |
|||
} |
|||
``` |
|||
|
|||
</YouWillLearnCard> |
|||
|
|||
### Elements {/*elements*/} |
|||
|
|||
<YouWillLearnCard title="Fragment" path="/apis/react/Fragment"> |
|||
|
|||
Return multiple elements: |
|||
|
|||
```js |
|||
function MyComponent() { |
|||
return ( |
|||
<> |
|||
<h1>Title</h1> |
|||
<h2>Subtitle</h2> |
|||
</> |
|||
); |
|||
} |
|||
``` |
|||
|
|||
</YouWillLearnCard> |
|||
|
|||
<YouWillLearnCard title="Children" path="/apis/react/Children"> |
|||
|
|||
Utilities for dealing with `props.children`: |
|||
|
|||
```js |
|||
React.Children.map(children, () => ([])); |
|||
|
|||
React.Children.forEach(children, () => {}); |
|||
|
|||
React.Children.count(children); |
|||
|
|||
React.Children.only(children); |
|||
|
|||
React.Children.toArray(children); |
|||
``` |
|||
|
|||
</YouWillLearnCard> |
|||
|
|||
<YouWillLearnCard title="createElement" path="/apis/react/createElement"> |
|||
|
|||
Create a React element: |
|||
|
|||
```js |
|||
React.createElement('div', { title: 'Element'}); |
|||
``` |
|||
|
|||
</YouWillLearnCard> |
|||
|
|||
<YouWillLearnCard title="createFactory" path="/apis/react/createFactory"> |
|||
|
|||
Create a factory for React elements of a given type: |
|||
|
|||
```js |
|||
React.createFactory('div'); |
|||
``` |
|||
|
|||
</YouWillLearnCard> |
|||
|
|||
<YouWillLearnCard title="cloneElement" path="/apis/react/cloneElement"> |
|||
|
|||
Clone a React element: |
|||
|
|||
```js |
|||
React.cloneElement(element, props); |
|||
``` |
|||
|
|||
</YouWillLearnCard> |
|||
|
|||
<YouWillLearnCard title="isValidElement" path="/apis/react/isValidElement"> |
|||
|
|||
Verifies the object is a React element: |
|||
|
|||
```js |
|||
React.isValidElement(object) |
|||
``` |
|||
|
|||
</YouWillLearnCard> |
|||
|
|||
### Suspense {/*suspense*/} |
|||
|
|||
<YouWillLearnCard title="React.lazy" path="/apis/react/lazy"> |
|||
|
|||
Define a component that is loaded dynamically: |
|||
|
|||
```js |
|||
const SomeComponent = React.lazy(() => import('./SomeComponent')); |
|||
``` |
|||
|
|||
</YouWillLearnCard> |
|||
|
|||
<YouWillLearnCard title="Suspense" path="/apis/react/Suspense"> |
|||
|
|||
Define Suspense boundaries: |
|||
|
|||
```js |
|||
<React.Suspense fallback={<Spinner />}> |
|||
//... |
|||
</React.Suspense> |
|||
``` |
|||
|
|||
</YouWillLearnCard> |
|||
|
|||
### Transitions {/*transitions*/} |
|||
|
|||
<YouWillLearnCard title="startTransition" path="/apis/react/startTransition"> |
|||
|
|||
Mark updates as transitions: |
|||
|
|||
```js |
|||
startTransition(() => { |
|||
setState(c => c + 1); |
|||
}); |
|||
``` |
|||
|
|||
</YouWillLearnCard> |
|||
|
|||
<YouWillLearnCard title="useTransition" path="/apis/react/startTransition"> |
|||
|
|||
Mark updates as transitions with pending flags: |
|||
|
|||
```js |
|||
const [isPending, startTransition] = useTransition(); |
|||
``` |
|||
|
|||
</YouWillLearnCard> |
|||
|
|||
<YouWillLearnCard title="useDeferredValue" path="/apis/react/useDeferredValue"> |
|||
|
|||
Defer to more urgent updates: |
|||
|
|||
```js |
|||
const deferredValue = useDeferredValue(value); |
|||
``` |
|||
|
|||
</YouWillLearnCard> |
|||
|
|||
### Effects {/*effects*/} |
|||
|
|||
<YouWillLearnCard title="useEffect" path="/apis/react/useEffect"> |
|||
|
|||
Synchronize external state: |
|||
|
|||
```js |
|||
useEffect(() => { |
|||
const unsubscribe = socket.connect(props.userId); |
|||
|
|||
return () => { |
|||
unsubscribe(); |
|||
} |
|||
}, [props.userId]) |
|||
``` |
|||
|
|||
</YouWillLearnCard> |
|||
|
|||
<YouWillLearnCard title="useLayoutEffect" path="/apis/react/useLayoutEffect"> |
|||
|
|||
Read layout DOM state: |
|||
|
|||
```js |
|||
useLayoutEffect(() => { |
|||
// Read DOM layout |
|||
}) |
|||
``` |
|||
|
|||
</YouWillLearnCard> |
|||
|
|||
<YouWillLearnCard title="useInsertionEffect" path="/apis/react/useInsertionEffect"> |
|||
|
|||
Insert styles into the DOM. |
|||
|
|||
```js |
|||
useInsertionEffect(() => { |
|||
// Insert styles |
|||
}) |
|||
``` |
|||
|
|||
</YouWillLearnCard> |
|||
|
|||
### Memoization {/*memoization*/} |
|||
|
|||
<YouWillLearnCard title="useCallback" path="/apis/react/useCallback"> |
|||
|
|||
Return a memoized callback. |
|||
|
|||
```js |
|||
const memoizedCallback = useCallback(callback, [...deps]); |
|||
``` |
|||
|
|||
</YouWillLearnCard> |
|||
|
|||
<YouWillLearnCard title="useMemo" path="/apis/react/useMemo"> |
|||
|
|||
Return a memoized value. |
|||
|
|||
```js |
|||
const memoizedValue = useMemo(() => value, [...deps]); |
|||
``` |
|||
|
|||
</YouWillLearnCard> |
|||
|
|||
<YouWillLearnCard title="memo" path="/apis/react/memo"> |
|||
|
|||
Return a memoized component. |
|||
|
|||
```js |
|||
const MyComponent = React.memo(function MyComponent(props) { |
|||
// ... |
|||
}); |
|||
``` |
|||
|
|||
</YouWillLearnCard> |
|||
|
|||
### Subscribing {/*subscribing*/} |
|||
|
|||
<YouWillLearnCard title="useSyncExternalStore" path="/apis/react/useSyncExternalStore"> |
|||
|
|||
Subscribe to external state. |
|||
|
|||
```js |
|||
const state = useSyncExternalStore(subscribe, getSnapshot); |
|||
``` |
|||
|
|||
</YouWillLearnCard> |
|||
|
|||
### Accessibility {/*accessibility*/} |
|||
|
|||
<YouWillLearnCard title="useId" path="/apis/react/useId"> |
|||
|
|||
Generate unique IDs across the server and client: |
|||
|
|||
```js |
|||
const id = useId(); |
|||
``` |
|||
|
|||
</YouWillLearnCard> |
|||
|
|||
### Debugging {/*devtools*/} |
|||
|
|||
<YouWillLearnCard title="StrictMode" path="/apis/react/StrictMode"> |
|||
|
|||
Eagerly highlight potential problems. |
|||
|
|||
```js |
|||
<StrictMode>{...}</StrictMode> |
|||
``` |
|||
|
|||
</YouWillLearnCard> |
|||
|
|||
<YouWillLearnCard title="useDebugValue" path="/apis/react/useDebugValue"> |
|||
|
|||
Display a label for custom hooks. |
|||
|
|||
```js |
|||
useDebugValue('Custom Label'); |
|||
``` |
|||
|
|||
</YouWillLearnCard> |
|||
|
|||
|
|||
This section is incomplete and is still being written! |
|||
|
|||
@ -0,0 +1,20 @@ |
|||
--- |
|||
title: isValidElement |
|||
--- |
|||
|
|||
<Wip> |
|||
|
|||
This section is incomplete, please see the old docs for [isValidElement](https://reactjs.org/docs/react-api.html#isvalidelement). |
|||
|
|||
</Wip> |
|||
|
|||
|
|||
<Intro> |
|||
|
|||
Verifies the object is a React element. Returns true or false. |
|||
|
|||
```js |
|||
React.isValidElement(object) |
|||
``` |
|||
|
|||
</Intro> |
|||
@ -0,0 +1,21 @@ |
|||
--- |
|||
title: lazy |
|||
--- |
|||
|
|||
<Wip> |
|||
|
|||
This section is incomplete, please see the old docs for [lazy](https://reactjs.org/docs/react-api.html#reactlazy). |
|||
|
|||
</Wip> |
|||
|
|||
|
|||
<Intro> |
|||
|
|||
`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. |
|||
|
|||
```js |
|||
// This component is loaded dynamically |
|||
const SomeComponent = React.lazy(() => import('./SomeComponent')); |
|||
``` |
|||
|
|||
</Intro> |
|||
@ -0,0 +1,20 @@ |
|||
--- |
|||
title: React.memo |
|||
--- |
|||
|
|||
<Wip> |
|||
|
|||
This section is incomplete, please see the old docs for [React.memo](https://reactjs.org/docs/react-api.html#reactmemo). |
|||
|
|||
</Wip> |
|||
|
|||
|
|||
<Intro> |
|||
|
|||
```js |
|||
const MyComponent = React.memo(function MyComponent(props) { |
|||
/* render using props */ |
|||
}); |
|||
``` |
|||
|
|||
</Intro> |
|||
@ -0,0 +1,18 @@ |
|||
--- |
|||
title: startTransition |
|||
--- |
|||
|
|||
<Wip> |
|||
|
|||
This section is incomplete, please see the old docs for [startTransition](https://reactjs.org/docs/react-api.html#starttransition). |
|||
|
|||
</Wip> |
|||
|
|||
|
|||
<Intro> |
|||
|
|||
```js |
|||
React.startTransition(callback); |
|||
``` |
|||
|
|||
</Intro> |
|||
@ -0,0 +1,18 @@ |
|||
--- |
|||
title: useCallback |
|||
--- |
|||
|
|||
<Wip> |
|||
|
|||
This section is incomplete, please see the old docs for [useCallback](https://reactjs.org/docs/hooks-reference.html#usecallback). |
|||
|
|||
</Wip> |
|||
|
|||
|
|||
<Intro> |
|||
|
|||
```js |
|||
const memoizedCallback = useCallback(callback, [...dependencies]) |
|||
``` |
|||
|
|||
</Intro> |
|||
@ -0,0 +1,20 @@ |
|||
--- |
|||
title: useDebugValue |
|||
--- |
|||
|
|||
<Wip> |
|||
|
|||
This section is incomplete, please see the old docs for [useDebugValue](https://reactjs.org/docs/hooks-reference.html#usedebugvalue). |
|||
|
|||
</Wip> |
|||
|
|||
|
|||
<Intro> |
|||
|
|||
`useDebugValue` can be used to display a label for custom hooks in React DevTools. |
|||
|
|||
```js |
|||
useDebugValue(value) |
|||
``` |
|||
|
|||
</Intro> |
|||
@ -0,0 +1,20 @@ |
|||
--- |
|||
title: useDeferredValue |
|||
--- |
|||
|
|||
<Wip> |
|||
|
|||
This section is incomplete, please see the old docs for [useDeferredValue](https://reactjs.org/docs/hooks-reference.html#usedeferredvalue). |
|||
|
|||
</Wip> |
|||
|
|||
|
|||
<Intro> |
|||
|
|||
`useDeferredValue` accepts a value and returns a new copy of the value that will defer to more urgent updates. If the current render is the result of an urgent update, like user input, React will return the previous value and then render the new value after the urgent render has completed. |
|||
|
|||
```js |
|||
const deferredValue = useDeferredValue(value); |
|||
``` |
|||
|
|||
</Intro> |
|||
@ -0,0 +1,18 @@ |
|||
--- |
|||
title: useEffect |
|||
--- |
|||
|
|||
<Wip> |
|||
|
|||
This section is incomplete, please see the old docs for [useEffect](https://reactjs.org/docs/hooks-reference.html#useeffect). |
|||
|
|||
</Wip> |
|||
|
|||
|
|||
<Intro> |
|||
|
|||
```js |
|||
useEffect(callback, [...dependencies]) |
|||
``` |
|||
|
|||
</Intro> |
|||
@ -0,0 +1,26 @@ |
|||
--- |
|||
title: useId |
|||
--- |
|||
|
|||
<Wip> |
|||
|
|||
This section is incomplete, please see the old docs for [useId](https://reactjs.org/docs/hooks-reference.html#useid). |
|||
|
|||
</Wip> |
|||
|
|||
|
|||
<Intro> |
|||
|
|||
`useId` is a hook for generating unique IDs that are stable across the server and client, while avoiding hydration mismatches. |
|||
|
|||
```js |
|||
const id = useId(); |
|||
``` |
|||
|
|||
</Intro> |
|||
|
|||
<Gotcha> |
|||
|
|||
`useId` is not for generating keys in a list. Keys should be generated from your data. |
|||
|
|||
</Gotcha> |
|||
@ -0,0 +1,18 @@ |
|||
--- |
|||
title: useImperativeHandle |
|||
--- |
|||
|
|||
<Wip> |
|||
|
|||
This section is incomplete, please see the old docs for [useImperativeHandle](https://reactjs.org/docs/hooks-reference.html#useimperativehandle). |
|||
|
|||
</Wip> |
|||
|
|||
|
|||
<Intro> |
|||
|
|||
```js |
|||
useImperativeHandle(ref, createHandle, [deps]) |
|||
``` |
|||
|
|||
</Intro> |
|||
@ -0,0 +1,26 @@ |
|||
--- |
|||
title: useInsertionEffect |
|||
--- |
|||
|
|||
<Wip> |
|||
|
|||
This section is incomplete, please see the old docs for [useInsertionEffect](https://reactjs.org/docs/hooks-reference.html#useinsertioneffect). |
|||
|
|||
</Wip> |
|||
|
|||
|
|||
<Intro> |
|||
|
|||
The signateure is identical to `useEffect`, but it fires synchronously before all DOM mutations. Use this to inject styles into the DOM before reading layout in `useLayoutEffect`. Since this hook is limited in scope, this hook does not have access to refs and cannot schedule updates. |
|||
|
|||
```js |
|||
useInsertionEffect(didUpdate); |
|||
``` |
|||
|
|||
</Intro> |
|||
|
|||
<Gotcha> |
|||
|
|||
`useInsertionEffect` should be limited to css-in-js library authors. Prefer [`useEffect`](/apis/react/useEffect) or [`useLayoutEffect`](/apis/react/useLayoutEffect) instead. |
|||
|
|||
</Gotcha> |
|||
@ -0,0 +1,18 @@ |
|||
--- |
|||
title: useLayoutEffect |
|||
--- |
|||
|
|||
<Wip> |
|||
|
|||
This section is incomplete, please see the old docs for [useLayoutEffect](https://reactjs.org/docs/hooks-reference.html#uselayouteffect). |
|||
|
|||
</Wip> |
|||
|
|||
|
|||
<Intro> |
|||
|
|||
```js |
|||
useLayoutEffect(callback, [...dependencies]) |
|||
``` |
|||
|
|||
</Intro> |
|||
@ -0,0 +1,18 @@ |
|||
--- |
|||
title: useMemo |
|||
--- |
|||
|
|||
<Wip> |
|||
|
|||
This section is incomplete, please see the old docs for [useMemo](https://reactjs.org/docs/hooks-reference.html#usememo). |
|||
|
|||
</Wip> |
|||
|
|||
|
|||
<Intro> |
|||
|
|||
```js |
|||
const memoizedValue = useMemo(callback, [...dependencies]) |
|||
``` |
|||
|
|||
</Intro> |
|||
@ -0,0 +1,20 @@ |
|||
--- |
|||
title: useSyncExternalStore |
|||
--- |
|||
|
|||
<Wip> |
|||
|
|||
This section is incomplete, please see the old docs for [useSyncExternalStore](https://reactjs.org/docs/hooks-reference.html#usesyncexternalstore). |
|||
|
|||
</Wip> |
|||
|
|||
|
|||
<Intro> |
|||
|
|||
`useSyncExternalStore` is a hook recommended for reading and subscribing from external data sources in a way that’s compatible with concurrent rendering features like selective hydration and time slicing. |
|||
|
|||
```js |
|||
const state = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot?); |
|||
``` |
|||
|
|||
</Intro> |
|||
@ -0,0 +1,18 @@ |
|||
--- |
|||
title: useTransition |
|||
--- |
|||
|
|||
<Wip> |
|||
|
|||
This section is incomplete, please see the old docs for [useTransition](https://reactjs.org/docs/hooks-reference.html#usetransition). |
|||
|
|||
</Wip> |
|||
|
|||
|
|||
<Intro> |
|||
|
|||
```js |
|||
const [isPending, startTransition] = useTransition(); |
|||
``` |
|||
|
|||
</Intro> |
|||
@ -1,51 +0,0 @@ |
|||
--- |
|||
title: ReactDOM API |
|||
--- |
|||
|
|||
<Intro> |
|||
|
|||
The ReactDOM package lets you render React components on a webpage. |
|||
|
|||
</Intro> |
|||
|
|||
Typically, you will use ReactDOM at the top level of your app to display your components. You will either use it directly or a [framework](/learn/start-a-new-react-project#building-with-react-and-a-framework) may do it for you. Most of your components should *not* need to import this module. |
|||
|
|||
## Installation {/*installation*/} |
|||
|
|||
<PackageImport> |
|||
|
|||
<TerminalBlock> |
|||
|
|||
npm install react-dom |
|||
|
|||
</TerminalBlock> |
|||
|
|||
```js |
|||
// Importing a specific API: |
|||
import { createRoot } from 'react-dom/client'; |
|||
|
|||
// Importing all APIs together: |
|||
import * as ReactDOMClient from 'react-dom/client'; |
|||
``` |
|||
|
|||
</PackageImport> |
|||
|
|||
You'll also need to install the same version of [React](/apis/). |
|||
|
|||
## Browser Support {/*browser-support*/} |
|||
|
|||
ReactDOM supports all popular browsers, including Internet Explorer 9 and above. [Some polyfills are required](http://todo%20link%20to%20js%20environment%20requirements/) for older browsers such as IE 9 and IE 10. |
|||
|
|||
## Exports {/*exports*/} |
|||
|
|||
<YouWillLearnCard title="render" path="/apis/render"> |
|||
|
|||
Displays a React component inside a browser DOM node. |
|||
|
|||
```js |
|||
render(<App />, document.getElementById('root')); |
|||
``` |
|||
|
|||
</YouWillLearnCard> |
|||
|
|||
This section is incomplete and is still being written! |
|||
@ -1,14 +0,0 @@ |
|||
--- |
|||
title: ReactDOM Client APIs |
|||
--- |
|||
|
|||
<Intro> |
|||
|
|||
The ReactDOM client APIs let you render a React application in the browser. |
|||
|
|||
</Intro> |
|||
|
|||
Typically, you will use these APIs at the top level of your app to display your components. You will either use them directly or a [framework](/learn/start-a-new-react-project#building-with-react-and-a-framework) may do it for you. Most of your components should *not* need to import these APIs. |
|||
|
|||
|
|||
Note: This section is incomplete and is still being written! |
|||
Loading…
Reference in new issue