WordPress
@wordpress/element vs vanilla JavaScript: when to use each
Compare a WordPress interface built with @wordpress/element and plain JavaScript, with matching counter examples, dependency setup and practical tradeoffs.
A plugin settings page with connected inputs needs a different approach from a button that reveals a paragraph. Choosing a rendering library should follow the interface you are building.
This guide compares two implementations of the same small counter. Both work; the useful difference is how you manage state as the interface grows.
What is wp.element?
@wordpress/element is WordPress’s React-based package for building component interfaces. In a script that uses WordPress’s registered dependencies, its browser global is wp.element. This is different from the browser’s DOM Element class.
The examples below use createElement, createRoot and useState. createRoot requires WordPress 6.2 or later. No JSX compiler is needed for this browser-global example. See the official element package reference.
Without @wordpress/element: own the state and DOM updates
Place this markup on a plugin admin page:
<div id="pg-counter">
<button type="button">Add one</button>
<p role="status">Count: <span>0</span></p>
</div>
Load the following JavaScript after that markup, for example through an enqueued footer script:
const counter = document.getElementById('pg-counter');
if (counter) {
let count = 0;
const button = counter.querySelector('button');
const output = counter.querySelector('span');
button.addEventListener('click', () => {
count += 1;
output.textContent = String(count);
});
}
Here, the handler changes the value and updates its visible representation. That is easy to follow for one output. If a later feature adds a reset button, a disabled state and a summary elsewhere on the page, each path must keep all those outputs consistent.
A shared update function can keep vanilla code organised. Complexity is not proof that React is required.
With @wordpress/element: describe the interface from state
Use an empty mount point instead of the previous counter markup:
<div id="pg-counter-app"></div>
Save this as assets/counter.js in the plugin:
const { createElement: h, createRoot, useState } = wp.element;
function Counter() {
const [count, setCount] = useState(0);
return h('div', null,
h('button', {
type: 'button',
onClick: () => setCount(value => value + 1),
}, 'Add one'),
h('p', { role: 'status' }, `Count: ${count}`)
);
}
const target = document.getElementById('pg-counter-app');
if (target) {
createRoot(target).render(h(Counter));
}
Now the click changes state; the component describes the resulting interface. Avoid manually editing DOM nodes inside this root, since the renderer owns them.
Load the WordPress dependency deliberately
For this unbundled example, enqueue the script with wp-element as a dependency. Put this in the main plugin file and replace the page hook with the value returned by your own add_menu_page() or add_submenu_page() registration:
add_action( 'admin_enqueue_scripts', function ( $hook ) {
if ( 'toplevel_page_pg-demo' !== $hook ) {
return;
}
wp_enqueue_script(
'pg-counter',
plugins_url( 'assets/counter.js', __FILE__ ),
array( 'wp-element' ),
'1.0.0',
true
);
} );
This is the loading portion of an existing admin page, not a complete plugin. For a compiled project, source imports such as import { useState } from '@wordpress/element' need a build pipeline. Use the generated dependency asset file when your build produces one; installing an npm package alone does not enqueue browser dependencies. The official plugin page walkthrough covers a compiled approach.
With and without: the practical difference
| Decision | Plain JavaScript | @wordpress/element |
|---|---|---|
| Rendering | Update the relevant DOM nodes yourself | Describe output through components |
| Local state | Variables or your own state model | Hooks such as useState |
| Good starting point | A small independent enhancement | A component-based admin interface |
| Dependencies | No rendering runtime required | Load the WordPress element dependency |
| Main maintenance task | Keep handlers and visible state consistent | Keep component state and ownership clear |
My recommendation: use plain JavaScript for a small, isolated behavior. Consider element when several controls depend on shared state or you are extending an existing component interface. Do not mount another root inside the block editor’s managed interface; use its extension points.
Neither approach automatically saves data, validates permissions or makes a page faster. This counter intentionally stores nothing. A real settings screen still needs an authorised server-side save path and useful error handling.
For public block behavior that starts from PHP-rendered HTML, read the separate Interactivity API comparison. Before delivering an admin interface, apply the staging checklist.