WordPress
WordPress Interactivity API vs vanilla JavaScript: a practical comparison
Build a disclosure with and without the WordPress Interactivity API. Compare directives, local context, script modules and when native HTML is enough.
Suppose a WordPress block shows a short explanation when someone clicks “Delivery details.” You can write a DOM listener yourself or connect the markup to WordPress’s Interactivity API.
The result can look identical. What changes is the contract between your markup, state and JavaScript. This guide implements the same disclosure both ways.
What the Interactivity API provides
Available in WordPress 6.5 and later, the API connects HTML directives to a namespaced store. Local context can hold values for one block instance, while actions change those values. Read the official directives and store reference.
It is a different tool from @wordpress/element, which is used for React-based component rendering. An editor interface and a public block interaction do not have to use the same rendering model.
Without the API: a scoped DOM listener
Render this markup for each instance. In a PHP block template, generate a unique panel ID and escape it wherever it appears:
<?php $panel_id = wp_unique_id( 'pg-delivery-' ); ?>
<div data-pg-disclosure>
<button type="button" aria-expanded="true"
aria-controls="<?php echo esc_attr( $panel_id ); ?>">
Delivery details
</button>
<p id="<?php echo esc_attr( $panel_id ); ?>">
Delivery dates are confirmed before dispatch.
</p>
</div>
Load this script once after the markup, using the project’s normal enqueue process:
document.querySelectorAll('[data-pg-disclosure]').forEach(root => {
const button = root.querySelector('button');
const panel = root.querySelector('p');
button.addEventListener('click', () => {
const open = button.getAttribute('aria-expanded') === 'true';
button.setAttribute('aria-expanded', String(!open));
panel.hidden = open;
});
});
Each instance finds its own controls. The content starts visible so it remains readable if JavaScript fails. This example initialises existing instances once; dynamically inserted markup needs its own initialisation strategy.
With the API: bind markup to local context
For a registered dynamic block, use this in render.php:
<?php $panel_id = wp_unique_id( 'pg-delivery-' ); ?>
<div
<?php echo get_block_wrapper_attributes(); ?>
data-wp-interactive="pg/delivery"
<?php echo wp_interactivity_data_wp_context( array( 'isOpen' => true ) ); ?>
>
<button type="button"
aria-expanded="true"
aria-controls="<?php echo esc_attr( $panel_id ); ?>"
data-wp-on--click="actions.toggle"
data-wp-bind--aria-expanded="context.isOpen">
Delivery details
</button>
<p id="<?php echo esc_attr( $panel_id ); ?>"
data-wp-bind--hidden="!context.isOpen">
Delivery dates are confirmed before dispatch.
</p>
</div>
Then define the action in the block’s view.js source:
import { store, getContext } from '@wordpress/interactivity';
store('pg/delivery', {
actions: {
toggle() {
const context = getContext();
context.isOpen = !context.isOpen;
},
},
});
The action changes one local value. Bindings express which attributes depend on it. Put context on each instance so opening one panel does not open every panel using the same store namespace.
These are implementation excerpts for an existing block, not a complete installable plugin. Translate visible strings in a production plugin.
Configure the block and build correctly
Merge these entries into the block’s existing block.json, preserving its other support flags and metadata:
{
"apiVersion": 3,
"supports": {
"interactivity": true
},
"render": "file:./render.php",
"viewScriptModule": "file:./view.js"
}
Register the built block directory on the server. Compile view.js with a module-aware WordPress build setup and deploy its generated dependency metadata, so @wordpress/interactivity resolves as a registered WordPress script module. Do not paste a bare package import into an ordinary classic script. The Core integration note explains the script-module loading model.
When WordPress processes a supported dynamic block, directives can also determine the initial server-rendered output. Keep the initial context consistent with the HTML fallback. The server rendering guide explains that boundary.
With and without: what changes?
| Concern | Plain JavaScript | Interactivity API |
|---|---|---|
| Click behavior | Attach an event listener | Reference a store action in markup |
| Expanded state | Update DOM attributes in your handler | Bind attributes to context |
| Repeated blocks | Scope selectors to each root | Give each instance local context |
| Loading | Enqueue the intended script | Use the script-module integration |
| Integration work | Own initialisation and DOM synchronisation | Own directives, context and module setup |
For a single disclosure, native HTML may be simpler than either implementation:
<details>
<summary>Delivery details</summary>
<p>Delivery dates are confirmed before dispatch.</p>
</details>
My recommendation: start with native HTML when it meets the requirement. Use a small script for an isolated enhancement. Consider the Interactivity API when building public blocks that benefit from a consistent directive and state model. It does not guarantee better performance or search rankings; measure the actual page.
What to test before release
Check keyboard activation, focus visibility and the expanded state. Put two instances on one page and confirm that they act independently. Disable JavaScript and verify that the explanation remains available. These checks matter in both implementations.
Use the WordPress staging checklist before release, and the plugin planning guide when the interaction grows into a larger workflow.