@wordpress/element 
Edit
Element is, quite simply, an abstraction layer atop React.
You may find yourself asking, “Why an abstraction layer?”. For a few reasons:
- In many applications, especially those extended by a rich plugin ecosystem as is the case with WordPress, it’s wise to create interfaces to underlying third-party code. The thinking is that if ever a need arises to change or even replace the underlying implementation, it can be done without catastrophic rippling effects to dependent code, so long as the interface stays the same.
- It provides a mechanism to shield implementers by omitting features with uncertain futures (
createClass,PropTypes). - It helps avoid incompatibilities between versions by ensuring that every plugin operates on a single centralized version of the code.
On the wp.element global object, you will find the following, ordered roughly by the likelihood you’ll encounter it in your code:
Installation
Install the module
npm install @wordpress/element --save
This package assumes that your code will run in an ES2015+ environment. If you’re using an environment that has limited or no support for such language features and APIs, you should include the polyfill shipped in @wordpress/babel-preset-default in your code.
Usage
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:
<div id="greeting"></div>
We can mount our app:
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 for a more thorough walkthrough, in most cases substituting React and ReactDOM with wp.element in code examples.
Why React?
At the risk of igniting debate surrounding any single “best” front-end framework, the choice to use any tool should be motivated specifically to serve the requirements of the system. In modeling the concept of a block, we observe the following technical requirements:
- An understanding of a block in terms of its underlying values (in the random image example, a category)
- A means to describe the UI of a block given these values
At its most basic, React provides a simple input / output mechanism. Given a set of inputs (“props”), a developer describes the output to be shown on the page. This is most elegantly observed in its function components. React serves the role of reconciling the desired output with the current state of the page.
The offerings of any framework necessarily become more complex as these requirements increase; many front-end frameworks prescribe ideas around page routing, retrieving and updating data, and managing layout. React is not immune to this, but the introduced complexity is rarely caused by React itself, but instead managing an arrangement of supporting tools. By moving these concerns out of sight to the internals of the system (WordPress core code), we can minimize the responsibilities of plugin authors to a small, clear set of touch points.
JSX
While not at all a requirement to use React, JSX is a recommended syntax extension to compose elements more expressively. Through a build process, JSX is converted back to the createElement syntax you see earlier in this document.
If you’ve configured Babel for your project, you can opt in to JSX syntax by specifying the pragma option of the transform-react-jsx plugin in your .babelrc configuration.
{
"plugins": [
[
"transform-react-jsx",
{
"pragma": "createElement"
}
]
]
}
This assumes that you will import the createElement function in any file where you use JSX. Alternatively, consider using the @wordpress/babel-plugin-import-jsx-pragma Babel plugin to automate the import of this function.
API
Children
Object that provides utilities for dealing with React children.
cloneElement
Creates a copy of an element with extended props.
Parameters
- element
WPElement: Element - props
?Object: Props to apply to cloned element
Returns
WPElement: Cloned element.
Component
A base class to create WordPress Components (Refs, state and lifecycle hooks)
concatChildren
Concatenate two or more React children objects.
Parameters
- childrenArguments
...?Object: Array of children arguments (array of arrays/strings/objects) to concatenate.
Returns
Array: The concatenated value.
createContext
Creates a context object containing two components: a provider and consumer.
Parameters
- defaultValue
Object: A default data stored in the context.
Returns
Object: Context object.
createElement
Returns a new element of given type. Type can be either a string tag name or another function which itself returns an element.
Parameters
- type
?(string|Function): Tag name or element creator - props
Object: Element properties, either attribute set to apply to DOM node or values to pass through to element creator - children
...WPElement: Descendant elements
Returns
WPElement: Element.
createInterpolateElement
This function creates an interpolated element from a passed in string with specific tags matching how the string should be converted to an element via the conversion map value.
Usage
For example, for the given string:
“This is a string with a link and a self-closing
tag”
You would have something like this as the conversionMap value:
{
span: <span />,
a: <a href={ 'https://github.com' } />,
CustomComponentB: <CustomComponent />,
}
Parameters
- interpolatedString
string: The interpolation string to be parsed. - conversionMap
Record<string, WPElement>: The map used to convert the string to a react element.
Returns
WPElement: A wp element.
createPortal
Creates a portal into which a component can be rendered.
Related
Parameters
- child
import('./react').WPElement: Any renderable child, such as an element, string, or fragment. - container
HTMLElement: DOM node into which element should be rendered.
createRef
Returns an object tracking a reference to a rendered element via its current property as either a DOMElement or Element, dependent upon the type of element rendered with the ref attribute.
Returns
Object: Ref object.
createRoot
Creates a new React root for the target DOM node.
Related
Changelog
6.2.0 Introduced in WordPress core.
findDOMNode
Finds the dom node of a React component.
Parameters
- component
import('./react').WPComponent: Component’s instance.
flushSync
Forces React to flush any updates inside the provided callback synchronously.
Parameters
- callback
Function: Callback to run synchronously.
forwardRef
Component enhancer used to enable passing a ref to its wrapped component. Pass a function argument which receives props and ref as its arguments, returning an element using the forwarded ref. The return value is a new component which forwards its ref.
Parameters
- forwarder
Function: Function passedpropsandref, expected to return an element.
Returns
WPComponent: Enhanced component.
Fragment
A component which renders its children without any wrapping element.
hydrate
Deprecated since WordPress 6.2.0. Use
hydrateRootinstead.
Hydrates a given element into the target DOM node.
Related
hydrateRoot
Creates a new React root for the target DOM node and hydrates it with a pre-generated markup.
Related
Changelog
6.2.0 Introduced in WordPress core.
isEmptyElement
Checks if the provided WP element is empty.
Parameters
- element
*: WP element to check.
Returns
boolean: True when an element is considered empty.
isValidElement
Checks if an object is a valid WPElement.
Parameters
- objectToCheck
Object: The object to be checked.
Returns
boolean: true if objectToTest is a valid WPElement and false otherwise.
lazy
Related
memo
Related
Platform
Component used to detect the current Platform being used. Use Platform.OS === ‘web’ to detect if running on web enviroment.
This is the same concept as the React Native implementation.
Related
- https://facebook.github.io/react-native/docs/platform-specific-code#platform-module Here is an example of how to use the select method:
Usage
import { Platform } from '@wordpress/element';
const placeholderLabel = Platform.select( {
native: __( 'Add media' ),
web: __(
'Drag images, upload new ones or select files from your library.'
),
} );
RawHTML
Component used as equivalent of Fragment with unescaped HTML, in cases where it is desirable to render dangerous HTML without needing a wrapper element. To preserve additional props, a div wrapper will be created if any props aside from children are passed.
Parameters
- props
RawHTMLProps: Children should be a string of HTML or an array of strings. Other props will be passed through to the div wrapper.
Returns
JSX.Element: Dangerously-rendering component.
render
Deprecated since WordPress 6.2.0. Use
createRootinstead.
Renders a given element into the target DOM node.
Related
renderToString
Serializes a React element to string.
Parameters
- element
import('react').ReactNode: Element to serialize. - context
[Object]: Context object. - legacyContext
[Object]: Legacy context object.
Returns
string: Serialized element.
startTransition
Related
StrictMode
Component that activates additional checks and warnings for its descendants.
Suspense
Related
switchChildrenNodeName
Switches the nodeName of all the elements in the children object.
Parameters
- children
?Object: Children object. - nodeName
string: Node name.
Returns
?Object: The updated children object.
unmountComponentAtNode
Deprecated since WordPress 6.2.0. Use
root.unmount()instead.
Removes any mounted element from the target DOM node.
Related
useCallback
Related
useContext
Related
useDebugValue
Related
useDeferredValue
Related
useEffect
Related
useId
Related
useImperativeHandle
Related
useInsertionEffect
Related
useLayoutEffect
Related
useMemo
Related
useReducer
Related
useRef
Related
useState
Related
useSyncExternalStore
Related
useTransition
Related
Contributing to this package
This is an individual package that’s part of the Gutenberg project. The project is organized as a monorepo. It’s made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to npm and used by WordPress as well as other software projects.
To find out more about contributing to this package or Gutenberg as a whole, please read the project’s main contributor guide.