Use WordPress's block-oriented reactive runtime when frontend elements need shared state, declarative DOM updates, or server-rendered markup that hydrates without changing. Do not use it merely to enqueue an unrelated JavaScript widget.
\n| Requirement | \nPrefer | \n
|---|---|
| One isolated click handler with no block integration | \nA small viewScript or viewScriptModule | \n
| Reactive state, directives, or communication between blocks | \nInteractivity API | \n
| Editor inspector/sidebar UI | \n@wordpress/data and Block Editor packages | \n
| Data persistence or privileged work | \nREST API with authorization; Interactivity API is only the UI/runtime layer | \n
Declare support and load a script module through block metadata:
\n{\n \"apiVersion\": 3,\n \"name\": \"acme/counter\",\n \"supports\": { \"interactivity\": true },\n \"render\": \"file:./render.php\",\n \"viewScriptModule\": \"file:./view.js\"\n}\nIn render.php, initialize public state and emit directives safely:
<?php\nwp_interactivity_state(\n 'acme/counter',\n array( 'total' => 0 )\n);\n\n$context = array( 'count' => (int) ( $attributes['start'] ?? 0 ) );\n?>\n<div\n data-wp-interactive=\"acme/counter\"\n <?php echo wp_interactivity_data_wp_context( $context ); // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- Core returns a complete escaped attribute. ?>\n>\n <output data-wp-text=\"context.count\"></output>\n <button type=\"button\" data-wp-on--click=\"actions.increment\">\n <?php esc_html_e( 'Increase', 'acme' ); ?>\n </button>\n</div>\nIn view.js:
import { getContext, store } from '@wordpress/interactivity';\n\nstore( 'acme/counter', {\n\tactions: {\n\t\tincrement() {\n\t\t\tconst context = getContext();\n\t\t\tcontext.count += 1;\n\t\t},\n\t},\n} );\nUse wp_register_script_module() only for modules not already registered through block.json. Do not enqueue the module as a classic script.
wp_interactivity_state( $namespace, $state ) defines store state shared by that namespace and recursively merges later calls.data-wp-context is local to an element subtree; use wp_interactivity_data_wp_context() instead of hand-building JSON attributes.wp_interactivity_config( $namespace, $config ) supplies immutable client configuration.wp_interactivity_get_context() and wp_interactivity_get_element() are meaningful only while the server is processing directives.Common directives are:
\ndata-wp-interactive=\"namespace\" establishes the store namespace.data-wp-on--click=\"actions.name\" attaches an event action.data-wp-bind--hidden=\"state.isHidden\" binds an HTML attribute.data-wp-class--is-open=\"context.isOpen\" toggles a class.data-wp-style--width=\"state.width\" updates one style property.data-wp-text=\"state.label\" updates text content.data-wp-init runs at element initialization; data-wp-watch reacts to accessed state.namespace::state.path or namespace::actions.name.Do not invent directive names or duplicate an attribute on the same element. When generating or modifying markup, prefer WP_HTML_Tag_Processor over regex or concatenation.
Server-side data-wp-bind now aligns more closely with the value sent to the client:
_doing_it_wrong() and the binding is treated as null.Therefore, derived state used by an attribute binding must resolve to a finite scalar or null. Do not bind an array to class, style, or another attribute and rely on PHP coercion.
Malformed directive names and missing namespaces are also handled more defensively in 7.1. Treat notices under WP_DEBUG as contract failures, not harmless noise.
Actions invoked by the runtime receive the correct scope. If an action continues in a timer, subscription, or other external callback, preserve scope with withScope(). Follow the package's generator-based async-action pattern where the installed WordPress version requires it; do not replace it blindly with an unscoped Promise callback.
getElement() gives the scoped element.data-wp-* attributes and the script module.WP_DEBUG and SCRIPT_DEBUG; resolve _doing_it_wrong() and console warnings.Read references/contracts-and-debugging.md for directive value semantics, lifecycle choices, and failure modes.
\nwordpress/wp-rest-api for authenticated persistence and endpoint contracts.wordpress/wp-html-api for safe server-side directive mutation.wordpress/wp-block-editor-iframe-compatibility for editor-canvas code.plugin-scaffold/wp-plugin-assets-loading for script-module and asset loading.references/contracts-and-debugging.md for the directive table, store contract and hydration-mismatch debugging.