Element

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:

• createElement
• render

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 ES2015+ such as lower versions of IE then using core-js or @babel/polyfill will add support for these methods. Learn more about it in Babel docs.

Usage

Let's render a customized greeting into an empty element:

<div id="greeting"></div>
<script>
function Greeting( props ) {
    return wp.element.createElement( 'span', null, 
        'Hello ' + props.toWhom + '!'
    );
}

wp.element.render(
    wp.element.createElement( Greeting, { toWhom: 'World' } ),
    document.getElementById( 'greeting' )
);
</script>

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

src/index.js#L1-L1

Object that provides utilities for dealing with React children.

cloneElement

src/index.js#L1-L1

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

src/index.js#L1-L1

A base class to create WordPress Components (Refs, state and lifecycle hooks)

concatChildren

src/index.js#L1-L1

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

src/index.js#L1-L1

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

src/index.js#L1-L1

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.

createPortal

src/index.js#L2-L2

Creates a portal into which a component can be rendered.

Related

• https://github.com/facebook/react/issues/10309#issuecomment-318433235

Parameters

• component Component: Component
• target Element: DOM node into which element should be rendered

createRef

src/index.js#L1-L1

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.

findDOMNode

src/index.js#L2-L2

Finds the dom node of a React component

Parameters

• component Component: component's instance
• target Element: DOM node into which element should be rendered

forwardRef

src/index.js#L1-L1

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 passed props and ref, expected to return an element.

Returns

WPComponent: Enhanced component.

Fragment

src/index.js#L1-L1

A component which renders its children without any wrapping element.

isEmptyElement

src/index.js#L3-L3

Checks if the provided WP element is empty.

Parameters

• element *: WP element to check.

Returns

boolean: True when an element is considered empty.

isValidElement

src/index.js#L1-L1

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.

RawHTML

src/index.js#L5-L5

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.children string: HTML to render.

Returns

WPElement: Dangerously-rendering element.

render

src/index.js#L2-L2

Renders a given element into the target DOM node.

Parameters

• element WPElement: Element to render
• target Element: DOM node into which element should be rendered

renderToString

src/index.js#L4-L4

Serializes a React element to string.

Parameters

• element WPElement: Element to serialize.
• context ?Object: Context object.
• legacyContext ?Object: Legacy context object.

Returns

string: Serialized element.

StrictMode

src/index.js#L1-L1

Component that activates additional checks and warnings for its descendants.

switchChildrenNodeName

src/index.js#L1-L1

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

src/index.js#L2-L2

Removes any mounted element from the target DOM node.

Parameters

• target Element: DOM node in which element is to be removed

useCallback

src/index.js#L1-L1

Related

• https://reactjs.org/docs/hooks-reference.html#usecallback

useContext

src/index.js#L1-L1

Related

• https://reactjs.org/docs/hooks-reference.html#usecontext

useDebugValue

src/index.js#L1-L1

Related

• https://reactjs.org/docs/hooks-reference.html#usedebugvalue

useEffect

src/index.js#L1-L1

Related

• https://reactjs.org/docs/hooks-reference.html#useeffect

useImperativeHandle

src/index.js#L1-L1

Related

• https://reactjs.org/docs/hooks-reference.html#useimperativehandle

useLayoutEffect

src/index.js#L1-L1

Related

• https://reactjs.org/docs/hooks-reference.html#uselayouteffect

useMemo

src/index.js#L1-L1

Related

• https://reactjs.org/docs/hooks-reference.html#usememo

useReducer

src/index.js#L1-L1

Related

• https://reactjs.org/docs/hooks-reference.html#usereducer

useRef

src/index.js#L1-L1

Related

• https://reactjs.org/docs/hooks-reference.html#useref

useState

src/index.js#L1-L1

Related

• https://reactjs.org/docs/hooks-reference.html#usestate