Interactivity API
Quick Definition
The Interactivity API is WordPress's built-in framework for adding dynamic, interactive behavior to blocks on the front end — like instant search, toggles, and shopping carts — without external JavaScript libraries.
What Is the Interactivity API?
The Interactivity API is a lightweight JavaScript framework built into WordPress core (since version 6.5) that provides a standardized way to add front-end interactions to blocks. Before it existed, developers had to write custom JavaScript — often using jQuery, Alpine.js, or even React — to make blocks interactive. Each plugin handled this differently, leading to conflicts, inconsistent behavior, and performance issues from loading multiple frameworks.
The Interactivity API solves this by giving every block developer the same tools. It works through three core concepts:
- Directives — Special HTML attributes you add to your block's markup to bind interactive behavior. The
wp-interactivedirective activates the API for a section of the page. Other directives likedata-wp-on--click,data-wp-bind--hidden, anddata-wp-textconnect elements to actions and state. - Store — A centralized state management system where you define your block's data, actions (functions that run on user interaction), and derived values (computed state). Think of it as the brain behind your interactive block.
- Context — A scoping mechanism that lets parent blocks pass data down to child blocks through the DOM tree, similar to React's context.
The API is declarative, not imperative. Instead of writing "when the user clicks this button, find element X and change its text," you declare "this element's text is bound to this state value" — and the API handles the updates automatically when the state changes. This is a fundamental shift from how jQuery-era WordPress plugins worked.
A key advantage is cross-block communication. Because all interactive blocks share the same framework, they can share state. An "Add to Cart" block can update a separate "Cart Total" block instantly without any custom event wiring. This is something that was extremely difficult before.
In WordPress 7.0, the Interactivity API gets a new watch() function that subscribes to reactive value changes and re-runs callbacks automatically — making it even more powerful for complex interactions.
Interactivity API in Practice
WordPress core already uses the Interactivity API in several built-in blocks: the Search block (instant search), the Query Loop block (client-side pagination), the Image block (lightbox), and the Navigation block (mobile overlay). When you see these features working without a full page reload, the Interactivity API is what powers them.
For developers, the API works directly with PHP and HTML — no React knowledge required, no build process needed for simple interactions. You write your block's markup in PHP, add directives as HTML attributes, and define the store in a small JavaScript file. It is designed to feel natural for WordPress developers who already know hooks and template tags.
Why It Matters
The Interactivity API is the future of front-end WordPress development. As WordPress moves toward more dynamic, app-like experiences — instant navigation, real-time collaboration, interactive forms — this API is the foundation everything builds on. Understanding it puts you ahead of the curve as WordPress evolves from a static CMS into a modern application platform.