The WordPress Interactivity API: Dynamic Frontends Without a Heavy JavaScript Framework

The WordPress Interactivity API answers a question that dogged block development for years: how should the front end of a block behave when it needs to react to users? The editor side of a block is React, but shipping React to visitors just to toggle a menu is absurd overkill, so developers improvised — a jQuery snippet here, a sprinkle of vanilla JavaScript there, an entire embedded framework somewhere else, none of it interoperable. The Interactivity API, which shipped in WordPress core and now powers core blocks like Navigation, Query Loop pagination, and Search, replaces that chaos with a standard: a lightweight, directive-based way to make server-rendered HTML reactive.

The core idea: directives on server-rendered markup

Instead of rendering your UI in JavaScript, you render it in PHP as WordPress always has, then annotate the HTML with directives — special data-wp-* attributes that declare behavior. A runtime (built on Preact signals, weighing a few kilobytes) reads those attributes and wires up reactivity. A toggle looks like this:

<div
  data-wp-interactive="myPlugin"
  <?php echo wp_interactivity_data_wp_context( array( 'isOpen' => false ) ); ?>
>
  <button
    data-wp-on--click="actions.toggle"
    data-wp-bind--aria-expanded="context.isOpen"
  >
    Details
  </button>
  <p data-wp-bind--hidden="!context.isOpen">
    Now you see me.
  </p>
</div>

And the accompanying store, in your block's view.js:

import { store, getContext } from '@wordpress/interactivity';

store( 'myPlugin', {
  actions: {
    toggle() {
      const context = getContext();
      context.isOpen = ! context.isOpen;
    },
  },
} );

That is the entire pattern. data-wp-interactive activates a region and names its store. data-wp-context provides local state scoped to that element and its children. data-wp-on--click attaches an event handler, and data-wp-bind--* keeps attributes synchronized with state. When isOpen changes, everything bound to it updates — no manual DOM bookkeeping, no re-render of anything unrelated.

Why this beats both jQuery and React here

Compared to hand-rolled JavaScript, directives are declarative: behavior is visible in the markup, state changes propagate automatically, and two interactive blocks made by different authors can coexist and even communicate, because they share one runtime and convention. Compared to a framework like React on the frontend, the wins are architectural:

• Server rendering stays primary. The HTML visitors and crawlers receive is complete and meaningful before any JavaScript runs. There is no hydration flash, no client-side data fetching for the initial view, and graceful degradation is the default posture.
• The payload is tiny. The runtime is a few kilobytes shared by every interactive block on the page, and view scripts are loaded as ES modules only when a page actually contains the block. Core also supports deferring that work further with module loading strategies.
• State is composable. Global store values and element-scoped context cover the real-world cases — a mini-cart in the header reacting to an add-to-cart button in the content — without prop-drilling or event-bus hacks.
• PHP participates. Initial state can be set server-side with wp_interactivity_state(), so the first render is correct without a client round trip.

The directive vocabulary you actually use

A handful of directives cover most components. data-wp-bind--attribute binds any HTML attribute to state. data-wp-class--name and data-wp-style--property toggle classes and inline style properties. data-wp-text sets text content. data-wp-on--event (and its window and document variants) handles events. data-wp-watch runs a callback when its dependencies change — useful for side effects like focusing an element when a modal opens. data-wp-each renders a list from array state. Derived values live in the store as getters, so a state.filteredItems can compute from state.items and state.query and everything bound to it stays current.

Region-based navigation: the SPA feeling without the SPA

One capability deserves special mention. The API includes a router (still officially experimental for general use) that can intercept navigation, fetch the next page's HTML, and swap only a designated region of the DOM while preserving state — this is what gives core's Query Loop block its instant, no-reload pagination. Combined with directives, this delivers the smooth-navigation feel people build SPAs for, while every URL remains a real, server-rendered page. For content sites with filtering, pagination, and search, that is most of the SPA value at almost none of the SPA cost.

Where it fits — and where it does not

The Interactivity API is the right tool for the interactive layer of content sites: navigation menus, accordions and tabs, image lightboxes, product filters, instant search, favorites and like buttons, mini-carts, countdowns, and multi-step forms. It is deliberately not a general application framework. If you are building something that is fundamentally an app — a dashboard with complex client-side routing, offline behavior, and heavy data mutation — a dedicated framework remains the better fit, likely in a headless or embedded-app architecture. The API's sweet spot is precisely the territory where reaching for React always felt heavy and reaching for jQuery always felt flimsy.

Practical adoption notes: directives work in block themes and classic themes alike, but the API assumes blocks as the delivery mechanism, so the natural home for your code is a block's render.php and view.js (scaffold with npx @wordpress/create-block --template @wordpress/create-block-interactive-template). Interactive regions require well-formed HTML, and server-updated regions must be rendered through the block so the directives survive. And because the runtime is shared, avoid loading a second copy through bundling mistakes — import from @wordpress/interactivity and let WordPress provide it as a script module.

The bottom line

The Interactivity API is the most consequential front-end change WordPress has shipped since blocks themselves. It gives the platform a native answer to reactivity that respects what WordPress already does well — render HTML on the server, fast — while eliminating the framework tax for everyday interactivity. If you build blocks, plugins, or themes with any dynamic behavior, this is now the standard way to do it, and the sites that adopt it ship less JavaScript, pass INP more comfortably, and interoperate better with everything else in the ecosystem.