Developer · Guide
How to Use the Interactivity API in WordPress
Short answer
To use the Interactivity API in WordPress, scaffold an interactive block with the official template, set supports.interactivity to true in block.json, write a store in view.js, and add data-wp-* directives to your markup. You need WordPress 6.5 or later, Node.js, and a local test site, and you finish by building the block and clicking through it on the front end.
Key takeaways
- The Interactivity API is built into WordPress 6.5 and later, so no extra library is needed on a current site.
- Add data-wp-interactive with your store namespace to switch on interactivity for an element and its children.
- Keep shared data in the store state and per-instance data in data-wp-context.
- Set starting state in PHP with wp_interactivity_state so the first page load already shows the right values.
- Load your JavaScript as a script module with viewScriptModule, not as a plain view script.
What do you need before you start using the Interactivity API?
You need WordPress 6.5 or later, a local WordPress site, Node.js with npm, and a code editor before you write any interactive code.
The Interactivity API Reference from the Block Editor Handbook says the API was introduced in WordPress 6.5 and is bundled in core from that version (checked November 2026). The same reference says sites below WordPress 6.5 need Gutenberg 17.5 or higher installed and active.
Check each item before you start, so a missing tool does not stop you halfway through.
- WordPress 6.5 or later on a local test site, not your live site.
- Node.js and npm installed on your computer.
- A code editor for PHP, JavaScript, and JSON files.
- A way to run commands in a terminal.
| Item | Why you need it | How to check it |
|---|---|---|
| WordPress 6.5 or later | The API is bundled in core from 6.5 | Dashboard → Updates shows your version |
| Node.js and npm | Scaffolding and building need them | Run node -v and npm -v in a terminal |
| Local WordPress site | Safe place to activate a new block | Open the local site in a browser |
| Code editor | You edit block.json, view.js, and render.php | Open the plugin folder in the editor |
Plan for about 1 to 2 hours for a first toggle or counter block, including setup time.
How do you scaffold your first interactive block?
Scaffold the block with the official interactive template, then start the development server in the new plugin folder.
The Quick start guide from the Block Editor Handbook gives one command that creates a complete “My First Interactive Block” plugin. Run it from the folder where you want the plugin to live.
npx @wordpress/create-block@latest my-first-interactive-block --template @wordpress/create-block-interactive-template
The slug you pass sets the folder name and the internal block name. The template is published as @wordpress/create-block-interactive-template on npm, and the handbook says the flag for script modules is already included in its package.json scripts.
Then move into the folder and start development:
- Run
cd my-first-interactive-blockto enter the plugin folder. - Run
npm startto watch for changes and rebuild the block as you edit. - Activate the plugin on your local WordPress site.
- Insert the “My First Interactive Block” block into a post or page.
- Publish the post or page and open it on the front end.
If you have no local site running, the handbook points to WordPress Playground. Run npx @wp-playground/cli server --auto-mount from the plugin folder to launch a site with the plugin installed.
How do you turn on interactivity in block.json?
Add "interactivity": true to the supports object in block.json, and point viewScriptModule at your view.js file.
The Interactivity API Reference from the Block Editor Handbook shows this exact block.json change. It also says JavaScript using the API should be a script module, so it can depend on @wordpress/interactivity.
{
"supports": {
"interactivity": true
},
"viewScriptModule": "file:./view.js"
}
Script modules have been available since WordPress 6.5, according to the same handbook reference. If you did not use the interactive template, add the --experimental-modules flag to the build and start scripts in package.json.
{
"scripts": {
"build": "wp-scripts build --experimental-modules",
"start": "wp-scripts start --experimental-modules"
}
}
A block and a plugin are not the same thing, and the choice affects where your code lives. Read theme vs plugin in WordPress if you are unsure which one should hold your block.
How do you write a store in view.js?
Write a store in view.js with store() from @wordpress/interactivity, using the same namespace you put in your markup.
The Directives and Store page from the Block Editor Handbook says the store holds the logic and data for the behaviour, including state, actions, and side effects. Directives in the markup then connect to that store.
First, install the package in your project if it is not there already:
npm install @wordpress/interactivity --save
Then import the store in view.js. The handbook reference shows this import line:
import { store } from '@wordpress/interactivity';
This example store holds one toggle action for a show and hide button:
import { store, getContext } from '@wordpress/interactivity';
store( 'myPlugin', {
actions: {
toggle: () => {
const context = getContext();
context.isOpen = ! context.isOpen;
}
}
} );
State is data that can change, such as whether a panel is open. Actions are functions that run when something happens, such as a click. Callbacks run as side effects when state changes.
Use getContext() inside an action to reach the local context of the element that fired the event. Keep the namespace string identical in view.js and in data-wp-interactive, or nothing will happen.
How do you add directives to your block markup?
Add data-wp-* directives to your markup in render.php for a dynamic block or save.js for a static block.
The Directives and Store page from the Block Editor Handbook says directives are custom attributes with the data- prefix, and that data-wp-interactive is required for the engine to work. That directive switches on interactivity for the element and its children.
| Directive | What it does | Example |
|---|---|---|
data-wp-interactive | Switches on interactivity and names the store | data-wp-interactive="myPlugin" |
data-wp-context | Sets local state for an element and its children | data-wp-context='{"isOpen": false}' |
data-wp-on--click | Runs an action on click | data-wp-on--click="actions.toggle" |
data-wp-bind--hidden | Binds an attribute to a value | data-wp-bind--hidden="!context.isOpen" |
data-wp-class--selected | Adds or removes a class | data-wp-class--selected="context.isSelected" |
data-wp-text | Sets the text inside an element | data-wp-text="context.text" |
data-wp-style--color | Sets an inline style | data-wp-style--color="context.color" |
This markup builds a toggle button and a panel that starts hidden. Put these attributes on a wrapper element, a button, and a paragraph:
- Wrapper:
data-wp-interactive="myPlugin"anddata-wp-context='{ "isOpen": false }'. - Button:
data-wp-on--click="actions.toggle"anddata-wp-bind--aria-expanded="context.isOpen", with the label Toggle. - Paragraph:
data-wp-bind--hidden="!context.isOpen", with the text “This element is now visible!”
When state or context changes, directives react and update only the parts of the page that depend on that data. That is the core idea in the handbook page: you declare the link between data and markup, and the API updates the page for you.
For classes, use kebab-case names such as is-dark instead of camelCase names such as isDark. HTML attributes are not case-sensitive, so data-wp-class--isDark and data-wp-class--isdark are treated the same way.
How do you set starting state on the server with PHP?
Set shared starting state in PHP with wp_interactivity_state(), and set per-element starting values with wp_interactivity_data_wp_context().
The server-side rendering guide from the Block Editor Handbook lists three steps: mark the block as interactive in block.json, initialise state or context, then add directives to the markup. WordPress then processes the directives on the server.
wp_interactivity_state( 'myPlugin', array(
'fruits' => array( 'Apple', 'Banana', 'Cherry' )
) );
For local context, build the attribute with the PHP helper instead of writing JSON by hand:
echo wp_interactivity_data_wp_context( array( 'isOpen' => false ) );
The Interactivity API in 6.5 dev note from Make WordPress Core says wp_interactivity_state() initialises state on the server so the HTML sent by the server matches the HTML after client hydration. The same dev note says the context helper escapes the array, which avoids errors from hand-written JSON strings.
Behind the scenes, WordPress uses wp_interactivity_process_directives() to find and process directives in the block HTML. The server guide says this step lets WordPress send the first page with the correct interactive state, for a faster initial render, and the client JavaScript then takes over without a full page reload.
How do you build and test the block on a local site?
Build the block with npm run build, activate it, insert it in a post, publish the post, and click the control on the front end.
The Quick start guide from the Block Editor Handbook says npm start watches for changes and rebuilds as you edit, while npm run build optimises the code and makes it ready for production. Use the build command before you judge the final result.
- Run
npm run buildin the plugin folder. - Go to Dashboard → Plugins and activate your block plugin.
- Create a new post and insert your interactive block.
- Publish the post and open it on the front end, not only in the editor.
- Click the button and watch the panel, text, or class change.
- Reload the page and check that the starting state is right again.
Back up the test site first if it holds anything you care about. See how to back up WordPress for the steps, and keep that backup until the block is working.
Test with more than one copy of the block on the same page if your block will appear that way. Each copy should keep its own local context and act on its own, without changing the other copy.
How do you check that the interaction worked?
Check that the first page load shows the right starting state, that a click changes only the linked element, and that no JavaScript error appears in the browser console.
Start with the visible result. Click the button once and confirm the panel opens, the text changes, or the class is added. Click it again and confirm it returns to the first state.
Then check these points in order:
- The starting state in the page source matches the state you set in PHP.
- Each click updates the linked element and nothing else on the page.
- The browser console shows no error after you click.
- A reload restores the starting state you set on the server.
- Two copies of the block on one page act on their own.
If the page feels slow after you add the block, check the rest of the site before blaming the API. Read how to speed up WordPress for the checks that cover caching, images, and hosting.
The API runtime is about 10 KB, according to the Interactivity API FAQ from the Block Editor Handbook. That small size is one reason the API suits simple front-end behaviour such as toggles, counters, and filters.
When should you use context instead of shared state?
Use context for data that belongs to one copy of a block, and use shared state for data that two or more blocks must read and change together.
The Directives and Store page from the Block Editor Handbook says context provides a local state for a specific HTML node and its children. It accepts a stringified JSON value, and deeper levels merge their own context with any parent context.
A single accordion panel is a good fit for context. Each panel keeps its own isOpen value, so opening one panel does not open the others on the page.
Shared state fits a cart and a cart total that live in separate blocks. The handbook reference says blocks can share data, actions, and callbacks, so clicking an “add to cart” block can update a separate cart block.
Ask one question when you choose: if a second copy of the block should change too, use shared state. If each copy should act alone, use context.
How do you handle lists and repeated items?
Use data-wp-each to render a list from an array, give each item its own context, and use data-wp-key so the API can tell items apart.
The server-side rendering guide from the Block Editor Handbook uses a fruit list with data-wp-each as its main example. It shows the list rendered on the server from state set with wp_interactivity_state().
Give each repeated item a context value that identifies it, such as its post ID or its slug. The action can then read that value with getContext() and act on the right item only.
The Directives and Store page from the Block Editor Handbook says data-wp-key assigns a unique key to an element, which helps the API identify it when it iterates through arrays of elements. Add a stable key for each item, not a random value that changes on every render.
If you add the block to a post or a page, the content type matters for where the list appears. See posts vs pages in WordPress if you need a refresher on the difference.
What mistakes should you avoid?
Avoid a namespace mismatch, a missing data-wp-interactive attribute, a plain view script, hand-written JSON, and camelCase class names.
- The namespace in
data-wp-interactiveand the namespace instore()must match exactly, or the block will stay still. - Do not leave out
data-wp-interactive; the handbook says it is required for the engine to work. - Do not load your code with
viewScriptwhen the API needs a script module; useviewScriptModulein block.json. - Do not write
data-wp-contextJSON by hand in PHP; usewp_interactivity_data_wp_context()so the value is escaped. - Do not use camelCase in
data-wp-class--names; use kebab-case such asis-dark. - Do not skip
npm run buildand judge the block only from the development server. - Do not put shared data in context when two blocks must stay in step; use shared state instead.
- Do not use
data-wp-htmlwith a plain string; the handbook says only a value fromasDangerousHTML()renders as HTML, by design.
The tracking issue for the Interactivity API docs on GitHub lists the handbook pages and examples the WordPress team links to. Check those pages first when a directive does not behave as you expect, before you add a second library.
If you build with the block editor rather than a page builder, the editor choice also shapes how your block is used. See Gutenberg vs Elementor for how the two approaches differ.
Frequently asked questions
Do I need a plugin to use the Interactivity API?
No. The API is built into WordPress 6.5 and later, so you do not install it as a separate plugin. You still need to build a block or add code that uses it, because the API is a developer tool, not a setting in the dashboard. Sites below WordPress 6.5 need Gutenberg 17.5 or higher.
Can I use the Interactivity API in a classic theme?
Yes, you can use it beyond blocks. The handbook says the standard can add interactive behaviour to the front end of any part of WordPress. Classic themes can process directives on the server with wp_interactivity_process_directives, and they still need to load the script module and set the store namespace.
Why does my block do nothing when I click it?
Check the namespace first. The name in data-wp-interactive must match the name in store() exactly. Then check that data-wp-interactive is present, that viewScriptModule points at view.js, and that you ran npm run build. Open the browser console too, because a JavaScript error there often names the broken file.
Should I use the Interactivity API or plain JavaScript?
Use the Interactivity API when a block needs state that changes the page, such as a toggle, a filter, or a shared cart total. It keeps the first page load server-rendered and updates only the linked parts of the page. Plain JavaScript may be simpler for a one-off effect with no shared state, but it does not give you the same server rendering.
Does the Interactivity API work with the Search and Query blocks?
Yes. WordPress core already uses the API in the Search, Query, Navigation, and File blocks. That means features such as instant search and Query pagination in core blocks already rely on the same directives and store system you use in a custom block.
Sources
- Interactivity API Reference WordPress Developer Resources
- Directives and Store WordPress Developer Resources
- Quick start guide WordPress Developer Resources
- Server-side rendering: Processing directives on the server WordPress Developer Resources
- Interactivity API in 6.5 Make WordPress Core
- @wordpress/create-block-interactive-template npm
Is your product missing, or something out of date?
Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.
Thanks — we review requests within 3 business days.
