diff --git a/packages/element/README.md b/packages/element/README.md index 37e91255753da9..ec4d725062c2b9 100755 --- a/packages/element/README.md +++ b/packages/element/README.md @@ -25,23 +25,33 @@ _This package assumes that your code will run in an **ES2015+** environment. If ## Usage -Let's render a customized greeting into an empty element: +Let's render a customized greeting into an empty element. + +**Note:** `createRoot` was introduced with React 18, which is bundled with WordPress 6.2. Therefore it may be necessary to mount your component depending on which version of WordPress (and therefore React) you are currently using. This is possible by checking for an undefined import and falling back to the React 17 method of mounting an app using `render`. + +Assuming the following root element is present in the page: ```html
- +``` + +We can mount our app: + +```js +import { createRoot, render, createElement } from '@wordpress/element'; + +function Greeting( props ) { + return createElement( 'span', null, 'Hello ' + props.toWhom + '!' ); +} + +const domElement = document.getElementById( 'greeting' ); +const uiElement = createElement( Greeting, { toWhom: 'World' } ); + +if ( createRoot ) { + createRoot( domElement ).render( uiElement ); +} else { + render( uiElement, domElement ); +} ``` Refer to the [official React Quick Start guide](https://reactjs.org/docs/hello-world.html) for a more thorough walkthrough, in most cases substituting `React` and `ReactDOM` with `wp.element` in code examples. @@ -203,7 +213,11 @@ Creates a new React root for the target DOM node. _Related_ -- +- + +_Changelog_ + +`6.2.0` Introduced in WordPress core. ### findDOMNode @@ -242,12 +256,13 @@ A component which renders its children without any wrapping element. ### hydrate +> **Deprecated** since WordPress 6.2.0. Use `hydrateRoot` instead. + Hydrates a given element into the target DOM node. -_Parameters_ +_Related_ -- _element_ `import('./react').WPElement`: Element to hydrate. -- _target_ `HTMLElement`: DOM node into which element should be hydrated. +- ### hydrateRoot @@ -255,7 +270,11 @@ Creates a new React root for the target DOM node and hydrates it with a pre-gene _Related_ -- +- + +_Changelog_ + +`6.2.0` Introduced in WordPress core. ### isEmptyElement @@ -334,12 +353,13 @@ _Returns_ ### render +> **Deprecated** since WordPress 6.2.0. Use `createRoot` instead. + Renders a given element into the target DOM node. -_Parameters_ +_Related_ -- _element_ `import('./react').WPElement`: Element to render. -- _target_ `HTMLElement`: DOM node into which element should be rendered. +- ### renderToString @@ -386,11 +406,13 @@ _Returns_ ### unmountComponentAtNode +> **Deprecated** since WordPress 6.2.0. Use `root.unmount()` instead. + Removes any mounted element from the target DOM node. -_Parameters_ +_Related_ -- _target_ `Element`: DOM node in which element is to be removed +- ### useCallback diff --git a/packages/element/src/react-platform.js b/packages/element/src/react-platform.js index 38ab823f357e6b..bd444b2828bef7 100644 --- a/packages/element/src/react-platform.js +++ b/packages/element/src/react-platform.js @@ -39,36 +39,39 @@ export { flushSync }; /** * Renders a given element into the target DOM node. * - * @param {import('./react').WPElement} element Element to render. - * @param {HTMLElement} target DOM node into which element should be rendered. + * @deprecated since WordPress 6.2.0. Use `createRoot` instead. + * @see https://react.dev/reference/react-dom/render */ export { render }; /** * Hydrates a given element into the target DOM node. * - * @param {import('./react').WPElement} element Element to hydrate. - * @param {HTMLElement} target DOM node into which element should be hydrated. + * @deprecated since WordPress 6.2.0. Use `hydrateRoot` instead. + * @see https://react.dev/reference/react-dom/hydrate */ export { hydrate }; /** * Creates a new React root for the target DOM node. * - * @see https://reactjs.org/docs/react-dom-client.html#createroot + * @since 6.2.0 Introduced in WordPress core. + * @see https://react.dev/reference/react-dom/client/createRoot */ export { createRoot }; /** * Creates a new React root for the target DOM node and hydrates it with a pre-generated markup. * - * @see https://reactjs.org/docs/react-dom-client.html#hydrateroot + * @since 6.2.0 Introduced in WordPress core. + * @see https://react.dev/reference/react-dom/client/hydrateRoot */ export { hydrateRoot }; /** * Removes any mounted element from the target DOM node. * - * @param {Element} target DOM node in which element is to be removed + * @deprecated since WordPress 6.2.0. Use `root.unmount()` instead. + * @see https://react.dev/reference/react-dom/unmountComponentAtNode */ export { unmountComponentAtNode };