@wordpress/element

The @wordpress/element package provides a React abstraction layer for WordPress, re-exporting React components and hooks with WordPress-specific enhancements.

Installation

npm install @wordpress/element --save

Why Use @wordpress/element?

This package:

Provides consistent React imports across WordPress
Adds WordPress-specific utilities
Simplifies React version management
Ensures compatibility with WordPress core

Basic Usage

import { createElement, useState } from '@wordpress/element';

function MyComponent() {
	const [ count, setCount ] = useState( 0 );

	return createElement(
		'button',
		{ onClick: () => setCount( count + 1 ) },
		`Count: ${ count }`
	);
}

With JSX:

import { useState } from '@wordpress/element';

function MyComponent() {
	const [ count, setCount ] = useState( 0 );

	return (
		<button onClick={ () => setCount( count + 1 ) }>
			Count: { count }
		</button>
	);
}

React Hooks

All standard React hooks are available:

useState

import { useState } from '@wordpress/element';

function Counter() {
	const [ count, setCount ] = useState( 0 );

	return (
		<div>
			<p>Count: { count }</p>
			<button onClick={ () => setCount( count + 1 ) }>
				Increment
			</button>
		</div>
	);
}

useEffect

import { useState, useEffect } from '@wordpress/element';

function DataFetcher() {
	const [ data, setData ] = useState( null );

	useEffect( () => {
		fetch( '/api/data' )
			.then( ( res ) => res.json() )
			.then( setData );
	}, [] );

	return <div>{ data ? JSON.stringify( data ) : 'Loading...' }</div>;
}

useContext

import { createContext, useContext } from '@wordpress/element';

const ThemeContext = createContext( 'light' );

function ThemedButton() {
	const theme = useContext( ThemeContext );
	return <button className={ theme }>Themed Button</button>;
}

useRef

import { useRef, useEffect } from '@wordpress/element';

function FocusInput() {
	const inputRef = useRef();

	useEffect( () => {
		inputRef.current.focus();
	}, [] );

	return <input ref={ inputRef } />;
}

useMemo

import { useMemo } from '@wordpress/element';

function ExpensiveComponent( { items } ) {
	const processedItems = useMemo(
		() => items.map( ( item ) => expensiveOperation( item ) ),
		[ items ]
	);

	return <ul>{ /* Render processed items */ }</ul>;
}

useCallback

import { useCallback, useState } from '@wordpress/element';

function Parent() {
	const [ count, setCount ] = useState( 0 );

	const handleClick = useCallback( () => {
		setCount( ( c ) => c + 1 );
	}, [] );

	return <Child onClick={ handleClick } />;
}

Components

Fragment

Render multiple elements without a wrapper.

import { Fragment } from '@wordpress/element';

function List() {
	return (
		<Fragment>
			<li>Item 1</li>
			<li>Item 2</li>
			<li>Item 3</li>
		</Fragment>
	);
}

// Short syntax
function List() {
	return (
		<>
			<li>Item 1</li>
			<li>Item 2</li>
		</>
	);
}

StrictMode

Enables additional checks and warnings.

import { StrictMode } from '@wordpress/element';

function App() {
	return (
		<StrictMode>
			<MyComponent />
		</StrictMode>
	);
}

Suspense

Handles loading states for lazy components.

import { Suspense, lazy } from '@wordpress/element';

const LazyComponent = lazy( () => import( './LazyComponent' ) );

function App() {
	return (
		<Suspense fallback={ <div>Loading...</div> }>
			<LazyComponent />
		</Suspense>
	);
}

WordPress-Specific Components

RawHTML

Renders unescaped HTML safely.

import { RawHTML } from '@wordpress/element';

function HTMLContent( { html } ) {
	return <RawHTML>{ html }</RawHTML>;
}

Platform

Detects the current platform.

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

const styles = Platform.select( {
	web: { padding: 20 },
	native: { padding: 10 },
} );

function MyComponent() {
	const isWeb = Platform.OS === 'web';
	return <div style={ styles }>Platform-specific content</div>;
}

String Utilities

createInterpolateElement

Creates elements from interpolated strings.

import { createInterpolateElement } from '@wordpress/element';
import { __ } from '@wordpress/i18n';

function Notice() {
	return createInterpolateElement(
		__( 'Read the <a>documentation</a> for more info.' ),
		{
			a: <a href="/docs" />,
		}
	);
}

concatChildren

Concatenates multiple children arrays.

import { concatChildren } from '@wordpress/element';

const combined = concatChildren( children1, children2 );

switchChildrenNodeName

Changes the element type of children.

import { switchChildrenNodeName } from '@wordpress/element';

const updated = switchChildrenNodeName( children, 'div' );

Element Creation

createElement

Creates React elements.

import { createElement } from '@wordpress/element';

const element = createElement(
	'div',
	{ className: 'container' },
	'Hello World'
);

cloneElement

Clones an element with new props.

import { cloneElement } from '@wordpress/element';

function EnhancedComponent( { children } ) {
	return cloneElement( children, {
		className: 'enhanced',
	} );
}

Refs

createRef

Creates a ref object.

import { createRef, Component } from '@wordpress/element';

class MyComponent extends Component {
	constructor( props ) {
		super( props );
		this.inputRef = createRef();
	}

	componentDidMount() {
		this.inputRef.current.focus();
	}

	render() {
		return <input ref={ this.inputRef } />;
	}
}

forwardRef

Forwards refs to child components.

import { forwardRef } from '@wordpress/element';

const FancyButton = forwardRef( ( props, ref ) => (
	<button ref={ ref } className="fancy">
		{ props.children }
	</button>
) );

Rendering

createRoot (React 18)

Creates a root for rendering.

import { createRoot } from '@wordpress/element';

const root = createRoot( document.getElementById( 'root' ) );
root.render( <App /> );

hydrateRoot (React 18)

Hydrates server-rendered markup.

import { hydrateRoot } from '@wordpress/element';

hydrateRoot( document.getElementById( 'root' ), <App /> );

render (Legacy)

import { render } from '@wordpress/element';

render( <App />, document.getElementById( 'root' ) );

Class Components

Component

Base class for components.

import { Component } from '@wordpress/element';

class Counter extends Component {
	constructor( props ) {
		super( props );
		this.state = { count: 0 };
	}

	increment = () => {
		this.setState( ( state ) => ( {
			count: state.count + 1,
		} ) );
	};

	render() {
		return (
			<button onClick={ this.increment }>
				Count: { this.state.count }
			</button>
		);
	}
}

PureComponent

Component with shallow prop/state comparison.

import { PureComponent } from '@wordpress/element';

class OptimizedComponent extends PureComponent {
	render() {
		return <div>{ this.props.data }</div>;
	}
}

Portals

createPortal

Renders children into a different DOM node.

import { createPortal } from '@wordpress/element';
import { useState } from '@wordpress/element';

function Modal( { children } ) {
	return createPortal(
		<div className="modal">{ children }</div>,
		document.body
	);
}

Context

createContext

Creates a context object.

import { createContext, useContext } from '@wordpress/element';

const UserContext = createContext();

function App() {
	return (
		<UserContext.Provider value={ { name: 'John' } }>
			<UserProfile />
		</UserContext.Provider>
	);
}

function UserProfile() {
	const user = useContext( UserContext );
	return <div>{ user.name }</div>;
}

Advanced Hooks

useLayoutEffect

Runs synchronously after DOM mutations.

import { useLayoutEffect, useState } from '@wordpress/element';

function Component() {
	const [ width, setWidth ] = useState( 0 );

	useLayoutEffect( () => {
		setWidth( window.innerWidth );
	}, [] );

	return <div>Width: { width }</div>;
}

useImperativeHandle

Customizes ref value.

import {
	forwardRef,
	useImperativeHandle,
	useRef,
} from '@wordpress/element';

const FancyInput = forwardRef( ( props, ref ) => {
	const inputRef = useRef();

	useImperativeHandle( ref, () => ( {
		focus: () => inputRef.current.focus(),
	} ) );

	return <input ref={ inputRef } />;
} );

Utilities

isValidElement

Checks if a value is a valid React element.

import { isValidElement } from '@wordpress/element';

if ( isValidElement( value ) ) {
	console.log( 'Valid element' );
}

isEmptyElement

Checks if an element is empty.

import { isEmptyElement } from '@wordpress/element';

if ( isEmptyElement( children ) ) {
	console.log( 'No children' );
}

Children

Utilities for working with children.

import { Children } from '@wordpress/element';

function Component( { children } ) {
	const count = Children.count( children );
	const array = Children.toArray( children );

	return <div>Child count: { count }</div>;
}

Best Practices

Always use @wordpress/element - Don’t import React directly
Prefer hooks - Use function components with hooks over classes
Memoize expensive operations - Use useMemo and useCallback
Follow React patterns - Element behaves like standard React
Handle errors - Use error boundaries for production code

Block API

Core Packages

Components

Core Blocks

​Installation

​Why Use @wordpress/element?

​Basic Usage

​React Hooks

​useState

​useEffect

​useContext

​useRef

​useMemo

​useCallback

​Components

​Fragment

​StrictMode

​Suspense

​WordPress-Specific Components

​RawHTML

​Platform

​String Utilities

​createInterpolateElement

​concatChildren

​switchChildrenNodeName

​Element Creation

​createElement

​cloneElement

​Refs

​createRef

​forwardRef

​Rendering

​createRoot (React 18)

​hydrateRoot (React 18)

​render (Legacy)

​Class Components

​Component

​PureComponent

​Portals

​createPortal

​Context

​createContext

​Advanced Hooks

​useLayoutEffect

​useImperativeHandle

​Utilities

​isValidElement

​isEmptyElement

​Children

​Best Practices

Build docs developers (and LLMs) love

Installation

Why Use @wordpress/element?

Basic Usage

React Hooks

useState

useEffect

useContext

useRef

useMemo

useCallback

Components

Fragment

StrictMode

Suspense

WordPress-Specific Components

RawHTML

Platform

String Utilities

createInterpolateElement

concatChildren

switchChildrenNodeName

Element Creation

createElement

cloneElement

Refs

createRef

forwardRef

Rendering

createRoot (React 18)

hydrateRoot (React 18)

render (Legacy)

Class Components

Component

PureComponent

Portals

createPortal

Context

createContext

Advanced Hooks

useLayoutEffect

useImperativeHandle

Utilities

isValidElement

isEmptyElement

Children

Best Practices