For a long time, adding interactivity to WordPress front ends meant every plugin and theme doing its own thing. One plugin loaded jQuery for tabs, another loaded a framework for filters, another wrote its own vanilla JavaScript for accordions. Pages ended up with multiple approaches loaded side by side, each with its own patterns and performance costs.
The Interactivity API, introduced in WordPress 6.5, aims to fix this. It provides a standard way to add interactive behaviour to blocks using declarative directives in HTML and small JavaScript stores. Core blocks use it, and plugin and theme developers can use it too.
I’ve started using it for client projects where blocks need front-end behaviour, and it’s a pleasant change. Here’s how it works and how to get started.
What the Interactivity API is for
It’s designed for front-end interactivity in blocks, like:
- Tabs and accordions.
- Show more and show less toggles.
- Filters and sorting for lists.
- Image lightboxes and galleries.
- Add to cart buttons and mini carts.
- Instant search.
- Navigation between pages without full reloads, in more advanced cases.
It’s not for building the block editor interface; that still uses React. It’s for what visitors see and interact with on the site.
The key ideas
Directives
Directives are special HTML attributes that start with data-wp-. They connect elements to state and actions:
- data-wp-interactive marks the root of an interactive region and names its store namespace.
- data-wp-context provides local data for that region.
- data-wp-on–click runs an action on click. Other events work the same way, like data-wp-on–keydown.
- data-wp-bind–attribute binds an attribute to a value, like hidden or aria-expanded.
- data-wp-class–name toggles a class based on a value.
- data-wp-text sets an element’s text content.
- data-wp-each renders lists.
- data-wp-watch runs a callback when values it uses change.
Stores
A store holds state, actions and callbacks, defined in JavaScript and namespaced to avoid conflicts between plugins.
State and context
- Global state is shared across all instances of a namespace on the page.
- Context is local to a specific element and its children, perfect for per-block data, like whether a particular accordion is open.
Server-side rendering
Directives are processed on the server too, so the initial HTML already reflects the correct state. Content is visible immediately and works for search engines, then JavaScript takes over for interaction. This is one of the API’s biggest advantages over client-only approaches.
Building a simple toggle block
Here’s a minimal example: a block that shows and hides additional content.
block.json
The block declares that it supports interactivity and loads a view script module:
render.php
The server renders the markup with directives:
The wp_interactivity_data_wp_context function outputs the context attribute safely encoded.
view.js
The JavaScript defines the store with an action:
When the button is clicked, the toggle action flips isOpen in the block’s context. The directives automatically update: aria-expanded changes and the hidden attribute is removed or added. There’s no manual DOM manipulation.
Each instance of the block on a page has its own context, so multiple toggles work independently.
Global state and derived values
For data shared across the page, use state. You can also define getters, called derived state, computed from other values:
Elements bound to state.count update automatically when items change.
Initial global state can be set on the server with wp_interactivity_state, so the first render already shows correct values:
Async actions and data fetching
Actions can be asynchronous using generator functions, which work with the API’s internals to keep context correct:
Use the REST API for data, and keep requests efficient.
Why this approach is good for WordPress
- Standardisation: plugins and themes using the same API can work together more predictably.
- Performance: the runtime is small, shared between blocks and loaded as JavaScript modules.
- Server rendering: content is in the initial HTML, good for SEO and perceived performance.
- Accessibility: binding aria attributes declaratively makes accessible patterns easier.
- Less code: directives handle DOM updates, so you write logic, not manipulation.
When to use it
Use the Interactivity API for front-end behaviour in custom blocks, especially when:
- Multiple instances of the block appear on a page.
- Interactivity needs to work with server-rendered content.
- You want consistency with core blocks.
For tiny enhancements, like a single toggle in a theme, simple vanilla JavaScript may still be enough. For very complex applications, like a full single-page app, a dedicated framework may suit better. The Interactivity API sits comfortably in between, covering most interactive needs on content and commerce sites.
Tips and pitfalls
- Use namespaces that match your plugin to avoid conflicts.
- Keep business logic on the server where possible, and treat the front end as presentation.
- Escape output in render.php as usual.
- Test without JavaScript, making sure server-rendered content is sensible before interactivity loads.
- Mind accessibility: use proper buttons, manage focus where needed and bind aria attributes.
- Check browser support for JavaScript modules, which is excellent in modern browsers.
- Follow the documentation, because the API continues to evolve with new directives and features in each WordPress release.
When I reach for it
On recent projects, I’ve used the Interactivity API for accordion FAQ blocks, a product filter on a small store, a “load more” button for a case studies archive and a simple tabbed pricing table. In each case, the block rendered complete, accessible HTML on the server, and a small view module added behaviour. The total JavaScript was tiny compared with the libraries I’d previously have used, and every instance on a page worked independently without extra effort.
Where I still avoid it is very simple theme enhancements, like a single mobile menu toggle, where a few lines of plain JavaScript are perfectly adequate, and complex application-like interfaces that need extensive client-side routing and state, where a full framework may be a better fit.
Learning resources
The WordPress developer documentation includes an Interactivity API reference and guides, and the create-block tool can scaffold an interactive block template to start from. Reading the source of core blocks that use the API, like the image lightbox, navigation or search blocks, is also a good way to see real-world patterns.
Debugging tips
If directives don’t seem to work, check that the block declares interactivity support, that the view module is actually loading on the page and that the namespace in data-wp-interactive matches the namespace used in your store. Typos in namespaces and directive names are the most common causes of silent failures. Browser developer tools show the module loading in the network panel and any errors in the console.
Progressive enhancement
Design interactive blocks so the server-rendered HTML is meaningful on its own. A FAQ block should show questions and answers even before JavaScript loads, then become collapsible once it does. This keeps content accessible to search engines, resilient on slow connections and usable if a script fails.
Keep stores small and focused
Each store should represent one feature or block family. Small, focused stores are easier to understand, test and reuse. If a store grows large with unrelated actions, split it into separate namespaces. That keeps behaviour predictable and makes it easier for other developers to extend your blocks without unexpected side effects.
Combining with the REST API
Interactive blocks often need fresh data, like filtered results or updated cart totals. Pair the Interactivity API with well-designed REST endpoints that return exactly the data the block needs. Keep responses small, validate input and check permissions on every endpoint, just as you would for any other API.
Start with one simple block, learn the patterns and build from there.
Once the patterns click, interactive blocks become quick to build and pleasant to maintain.
Frequently asked questions
Does the Interactivity API replace React?
Not in the editor. The block editor still uses React. The Interactivity API is for front-end behaviour on the published site.
Do I need a build step?
Using @wordpress/scripts with a block project is the most convenient approach, especially for modules. Simple modules can work without bundling, but tooling helps.
Can classic themes use it?
It’s built around blocks, so it works best with blocks rendered in any theme that supports them. The API is processed through block rendering.
Is it ready for production?
It has been part of WordPress core since 6.5, and core blocks use it. As with any newer API, check the documentation for your WordPress version.
Final thoughts
The Interactivity API brings a standard, efficient approach to front-end interactivity in WordPress. Mark interactive regions with directives, keep per-block data in context and shared data in global state, write small stores with actions, render initial state on the server and let directives update the page. For tabs, toggles, filters, carts and more, it offers a cleaner and faster alternative to loading separate scripts for every feature.




