Title: @wordpress/element
Published: March 9, 2021
Last modified: April 1, 2026

---

# @wordpress/element

## In this article

 * [Installation](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#installation)
 * [Why React?](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#why-react)
 * [API](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#api)
    - [Children](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#children)
    - [cloneElement](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#cloneelement)
    - [Component](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#component)
    - [concatChildren](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#concatchildren)
    - [createContext](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#createcontext)
    - [createElement](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#createelement)
    - [createInterpolateElement](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#createinterpolateelement)
    - [createPortal](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#createportal)
    - [createRef](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#createref)
    - [createRoot](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#createroot)
    - [findDOMNode](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#finddomnode)
    - [flushSync](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#flushsync)
    - [forwardRef](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#forwardref)
    - [Fragment](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#fragment)
    - [hydrate](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#hydrate)
    - [hydrateRoot](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#hydrateroot)
    - [isEmptyElement](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#isemptyelement)
    - [isValidElement](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#isvalidelement)
    - [lazy](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#lazy)
    - [memo](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#memo)
    - [Platform](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#platform)
    - [PureComponent](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#purecomponent)
    - [RawHTML](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#rawhtml)
    - [render](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#render)
    - [renderToString](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#rendertostring)
    - [startTransition](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#starttransition)
    - [StrictMode](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#strictmode)
    - [Suspense](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#suspense)
    - [switchChildrenNodeName](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#switchchildrennodename)
    - [unmountComponentAtNode](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#unmountcomponentatnode)
    - [useCallback](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#usecallback)
    - [useContext](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#usecontext)
    - [useDebugValue](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#usedebugvalue)
    - [useDeferredValue](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#usedeferredvalue)
    - [useEffect](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#useeffect)
    - [useId](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#useid)
    - [useImperativeHandle](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#useimperativehandle)
    - [useInsertionEffect](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#useinsertioneffect)
    - [useLayoutEffect](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#uselayouteffect)
    - [useMemo](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#usememo)
    - [useReducer](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#usereducer)
    - [useRef](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#useref)
    - [useState](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#usestate)
    - [useSyncExternalStore](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#usesyncexternalstore)
    - [useTransition](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#usetransition)
 * [Contributing to this package](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#contributing-to-this-package)

[ Back to top](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#wp--skip-link--target)

Element is a package that builds on top of [React](https://reactjs.org/) and provide
a set of utilities to work with React components and React elements.

## 󠀁[Installation](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#installation)󠁿

Install the module

    ```bash
    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`](https://github.com/WordPress/gutenberg/tree/HEAD/packages/babel-preset-default#polyfill)
in your code._

## 󠀁[Why React?](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#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](https://github.com/WordPress/gutenberg/tree/HEAD/packages/blocks/README.md),
we observe the following technical requirements:

 * An understanding of a block in terms of its underlying values (in the [random image example](https://github.com/WordPress/gutenberg/tree/HEAD/packages/blocks/README.md#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](https://reactjs.org/docs/components-and-props.html#functional-and-class-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.

## 󠀁[API](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#api)󠁿

### 󠀁[Children](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#children)󠁿

Object that provides utilities for dealing with React children.

### 󠀁[cloneElement](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#cloneelement)󠁿

Creates a copy of an element with extended props.

_Parameters_

 * _element_ `Element`: Element
 * _props_ `?Object`: Props to apply to cloned element

_Returns_

 * `Element`: Cloned element.

### 󠀁[Component](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#component)󠁿

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

### 󠀁[concatChildren](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#concatchildren)󠁿

Concatenate two or more React children objects.

_Parameters_

 * _childrenArguments_ `ReactNode[][]`: – Array of children arguments (array of 
   arrays/strings/objects) to concatenate.

_Returns_

 * `ReactNode[]`: The concatenated value.

### 󠀁[createContext](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#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](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#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_ `...Element`: Descendant elements

_Returns_

 * `Element`: Element.

### 󠀁[createInterpolateElement](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#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:

 and a self-closing
 tag”

You would have something like this as the conversionMap value:

    ```javascript
    {
        span: <span />,
        a: <a href={ 'https://github.com' } />,
        CustomComponentB: <CustomComponent />,
    }
    ```

_Parameters_

 * _interpolatedString_ `Input`: The interpolation string to be parsed.
 * _conversionMap_ `ConversionMap< InterpolationString< Input > >`: The map used
   to convert the string to a react element.

_Returns_

 * `ReactElement`: A wp element.

### 󠀁[createPortal](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#createportal)󠁿

Creates a portal into which a component can be rendered.

_Related_

 * [https://github.com/facebook/react/issues/10309#issuecomment-318433235](https://github.com/facebook/react/issues/10309#issuecomment-318433235)

_Parameters_

 * _child_ `React.ReactElement`: Any renderable child, such as an element, string,
   or fragment.
 * _container_ `HTMLElement`: DOM node into which element should be rendered.

### 󠀁[createRef](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#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](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#createroot)󠁿

Creates a new React root for the target DOM node.

_Related_

 * [https://react.dev/reference/react-dom/client/createRoot](https://react.dev/reference/react-dom/client/createRoot)

_Changelog_

`6.2.0` Introduced in WordPress core.

### 󠀁[findDOMNode](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#finddomnode)󠁿

Finds the dom node of a React component.

_Parameters_

 * _component_ `React.ComponentType`: Component’s instance.

### 󠀁[flushSync](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#flushsync)󠁿

Forces React to flush any updates inside the provided callback synchronously.

_Parameters_

 * _callback_ `Function`: Callback to run synchronously.

### 󠀁[forwardRef](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#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 passed `props` and `ref`, expected to return
   an element.

_Returns_

 * `Component`: Enhanced component.

### 󠀁[Fragment](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#fragment)󠁿

A component which renders its children without any wrapping element.

### 󠀁[hydrate](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#hydrate)󠁿

>  **Deprecated** since WordPress 6.2.0. Use `hydrateRoot` instead.

Hydrates a given element into the target DOM node.

_Related_

 * [https://react.dev/reference/react-dom/hydrate](https://react.dev/reference/react-dom/hydrate)

### 󠀁[hydrateRoot](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#hydrateroot)󠁿

Creates a new React root for the target DOM node and hydrates it with a pre-generated
markup.

_Related_

 * [https://react.dev/reference/react-dom/client/hydrateRoot](https://react.dev/reference/react-dom/client/hydrateRoot)

_Changelog_

`6.2.0` Introduced in WordPress core.

### 󠀁[isEmptyElement](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#isemptyelement)󠁿

Checks if the provided WP element is empty.

_Parameters_

 * _element_ `unknown`: WP element to check.

_Returns_

 * `boolean`: True when an element is considered empty.

### 󠀁[isValidElement](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#isvalidelement)󠁿

Checks if an object is a valid React Element.

_Parameters_

 * _objectToCheck_ `Object`: The object to be checked.

_Returns_

 * `boolean`: true if objectToTest is a valid React Element and false otherwise.

### 󠀁[lazy](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#lazy)󠁿

_Related_

 * [https://react.dev/reference/react/lazy](https://react.dev/reference/react/lazy)

### 󠀁[memo](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#memo)󠁿

_Related_

 * [https://react.dev/reference/react/memo](https://react.dev/reference/react/memo)

### 󠀁[Platform](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#platform)󠁿

Component used to detect the current Platform being used. Use Platform.OS === ‘web’
to detect if running on web environment.

This is the same concept as the React Native implementation.

_Related_

 * [https://reactnative.dev/docs/platform-specific-code#platform-module](https://reactnative.dev/docs/platform-specific-code#platform-module)
   Here is an example of how to use the select method:

_Usage_

    ```javascript
    import { Platform } from '@wordpress/element';

    const placeholderLabel = Platform.select( {
        native: __( 'Add media' ),
        web: __(
            'Drag images, upload new ones or select files from your library.'
        ),
    } );
    ```

### 󠀁[PureComponent](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#purecomponent)󠁿

_Related_

 * [https://react.dev/reference/react/PureComponent](https://react.dev/reference/react/PureComponent)

### 󠀁[RawHTML](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#rawhtml)󠁿

Component used to render unescaped HTML.

Note: The `renderElement` serializer will remove the `div` wrapper unless non-children
props are present; typically when preparing a block for saving.

_Usage_

    ```language-jsx
    import { RawHTML } from '@wordpress/element';

    const Component = () => (
        <RawHTML>
            <h3>Hello world</h3>
        </RawHTML>
    );
    // Edit: <div><h3>Hello world</h3></div>
    // save: <h3>Hello world</h3>
    ```

_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_

 * Dangerously-rendering component.

### 󠀁[render](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#render)󠁿

>  **Deprecated** since WordPress 6.2.0. Use `createRoot` instead.

Renders a given element into the target DOM node.

_Related_

 * [https://react.dev/reference/react-dom/render](https://react.dev/reference/react-dom/render)

### 󠀁[renderToString](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#rendertostring)󠁿

Serializes a React element to string.

_Parameters_

 * _element_ `React.ReactNode`:
 * _context_ `any`:
 * _legacyContext_ `Record< string, any >`:

### 󠀁[startTransition](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#starttransition)󠁿

_Related_

 * [https://react.dev/reference/react/startTransition](https://react.dev/reference/react/startTransition)

### 󠀁[StrictMode](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#strictmode)󠁿

Component that activates additional checks and warnings for its descendants.

### 󠀁[Suspense](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#suspense)󠁿

_Related_

 * [https://react.dev/reference/react/Suspense](https://react.dev/reference/react/Suspense)

### 󠀁[switchChildrenNodeName](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#switchchildrennodename)󠁿

Switches the nodeName of all the elements in the children object.

_Parameters_

 * _children_ `ReactNode`: Children object.
 * _nodeName_ `string`: Node name.

_Returns_

 * `ReactNode`: The updated children object.

### 󠀁[unmountComponentAtNode](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#unmountcomponentatnode)󠁿

>  **Deprecated** since WordPress 6.2.0. Use `root.unmount()` instead.

Removes any mounted element from the target DOM node.

_Related_

 * [https://react.dev/reference/react-dom/unmountComponentAtNode](https://react.dev/reference/react-dom/unmountComponentAtNode)

### 󠀁[useCallback](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#usecallback)󠁿

_Related_

 * [https://react.dev/reference/react/useCallback](https://react.dev/reference/react/useCallback)

### 󠀁[useContext](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#usecontext)󠁿

_Related_

 * [https://react.dev/reference/react/useContext](https://react.dev/reference/react/useContext)

### 󠀁[useDebugValue](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#usedebugvalue)󠁿

_Related_

 * [https://react.dev/reference/react/useDebugValue](https://react.dev/reference/react/useDebugValue)

### 󠀁[useDeferredValue](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#usedeferredvalue)󠁿

_Related_

 * [https://react.dev/reference/react/useDeferredValue](https://react.dev/reference/react/useDeferredValue)

### 󠀁[useEffect](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#useeffect)󠁿

_Related_

 * [https://react.dev/reference/react/useEffect](https://react.dev/reference/react/useEffect)

### 󠀁[useId](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#useid)󠁿

_Related_

 * [https://react.dev/reference/react/useId](https://react.dev/reference/react/useId)

### 󠀁[useImperativeHandle](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#useimperativehandle)󠁿

_Related_

 * [https://react.dev/reference/react/useImperativeHandle](https://react.dev/reference/react/useImperativeHandle)

### 󠀁[useInsertionEffect](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#useinsertioneffect)󠁿

_Related_

 * [https://react.dev/reference/react/useInsertionEffect](https://react.dev/reference/react/useInsertionEffect)

### 󠀁[useLayoutEffect](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#uselayouteffect)󠁿

_Related_

 * [https://react.dev/reference/react/useLayoutEffect](https://react.dev/reference/react/useLayoutEffect)

### 󠀁[useMemo](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#usememo)󠁿

_Related_

 * [https://react.dev/reference/react/useMemo](https://react.dev/reference/react/useMemo)

### 󠀁[useReducer](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#usereducer)󠁿

_Related_

 * [https://react.dev/reference/react/useReducer](https://react.dev/reference/react/useReducer)

### 󠀁[useRef](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#useref)󠁿

_Related_

 * [https://react.dev/reference/react/useRef](https://react.dev/reference/react/useRef)

### 󠀁[useState](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#usestate)󠁿

_Related_

 * [https://react.dev/reference/react/useState](https://react.dev/reference/react/useState)

### 󠀁[useSyncExternalStore](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#usesyncexternalstore)󠁿

_Related_

 * [https://react.dev/reference/react/useSyncExternalStore](https://react.dev/reference/react/useSyncExternalStore)

### 󠀁[useTransition](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#usetransition)󠁿

_Related_

 * [https://react.dev/reference/react/useTransition](https://react.dev/reference/react/useTransition)

## 󠀁[Contributing to this package](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-element/?output_format=md#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](https://www.npmjs.com/)
and used by [WordPress](https://make.wordpress.org/core/) 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](https://github.com/WordPress/gutenberg/tree/HEAD/CONTRIBUTING.md).

First published

March 9, 2021

Last updated

April 1, 2026

Edit article

[ Improve it on GitHub: @wordpress/element ](https://github.com/WordPress/gutenberg/edit/trunk/packages/element/README.md)

[  Previous: @wordpress/editor](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-editor/)

[  Next: @wordpress/env](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-env/)