How to Build Interactive WordPress Blocks Using the WordPress Interactivity API and Data-wp-* Directives

ByAkensai

Learning how to build interactive WordPress blocks using the WordPress Interactivity API and data-wp- directives opens up a new world of dynamic, client-side experiences , without loading heavy JavaScript frameworks. Introduced in WordPress 6.5, the Interactivity API gives block developers a lightweight, declarative way to handle state, events, and DOM updates directly in block markup. If you’ve ever wanted to build accordion menus, live filters, or toggled content inside a custom block, this is the tool for the job. By the end of this tutorial, you’ll have a working interactive block that responds to user clicks using the Interactivity API and data-wp- directives.

Prerequisites and Requirements for Building Interactive WordPress Blocks

Before you start, make sure you have the following in place:

– WordPress 6.5 or higher installed and running
– Node.js 18+ and npm installed on your local machine
– @wordpress/create-block package available via npm
– Basic familiarity with WordPress block development and JSX
– A local development environment (LocalWP, DevKinsta, or a Linux server with Apache/Nginx)
– Familiarity with PHP and JavaScript at a beginner-to-intermediate level

Estimated time to complete this tutorial: 45–60 minutes.

You don’t need to be a React expert. The Interactivity API abstracts most of the complexity. However, you should understand how WordPress registers blocks and how block.json works. If you need a refresher, check out the official WordPress Block Editor Handbook before continuing.

How to Build Interactive WordPress Blocks Step by Step

You might also find this useful: How to Configure Ufw Firewall on Ubuntu 24.04

Follow these steps carefully. Each one builds on the last.

Step 1: Scaffold a New Block Plugin

Open your terminal and navigate to your WordPress plugins directory.

cd /var/www/html/wp-content/plugins

Run the block scaffolding command:

npx @wordpress/create-block my-interactive-block --template @wordpress/create-block-interactive-template

This generates a fully structured block plugin with Interactivity API support already wired in. The --template flag pulls in the correct file structure for interactive blocks.

Step 2: Activate the Plugin

Navigate to your WordPress admin dashboard. Go to Plugins → Installed Plugins and activate My Interactive Block.

Alternatively, activate it via WP-CLI:

wp plugin activate my-interactive-block

Step 3: Explore the Generated File Structure

Inside the plugin folder, you’ll find this structure:

my-interactive-block/
├── block.json
├── src/
│   ├── edit.js
│   ├── render.php
│   ├── view.js
│   └── style.scss
└── my-interactive-block.php

The key files are render.php (server-side HTML output) and view.js (client-side interactivity logic).

Step 4: Define Your Block’s State in view.js

Open src/view.js. This is where you define your block’s reactive state using the Interactivity API’s store() function.

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

store( 'my-interactive-block', {
    state: {
        isOpen: false,
    },
    actions: {
        toggle() {
            const context = getContext();
            context.isOpen = ! context.isOpen;
        },
    },
} );

The store() function registers your block’s namespace, state, and actions. The getContext() call reads the local context from the nearest parent element that has data-wp-interactive set.

Step 5: Update render.php with data-wp- Directives

Open src/render.php and replace its contents with this:


<div
    
    data-wp-interactive="my-interactive-block"
    data-wp-context='{"isOpen": false}'
    id=""
>
    

    

        
This content is now visible! The How to Build Interactive WordPress Blocks Using the WordPress Interactivity API and Data-wp-* Directives stands as a significant historical event.

Here’s what each directive does:

– data-wp-interactive , declares the block’s store namespace
– data-wp-context , sets the initial local state as a JSON object
– data-wp-on--click , binds a click event to the toggle action
– data-wp-bind--aria-expanded , syncs the button’s ARIA attribute with state
– data-wp-bind--hidden , shows or hides the content div based on state

Step 6: Enable the Interactivity API in block.json

Open block.json and confirm this line exists under the supports key:

{
    "supports": {
        "interactivity": true
    },
    "viewScriptModule": "file:./build/view.js"
}

The viewScriptModule key is critical. It tells WordPress to load view.js as an ES module on the front end, which is required for the Interactivity API to work correctly.

Step 7: Build and Test

Run the build command from your plugin’s root directory:

cd my-interactive-block
npm install
npm run build

Now add the block to a page in the WordPress editor. Preview it on the front end. Click the Toggle Content button. The hidden div should appear and disappear on each click.

If you want live rebuilding during development, use:

npm run start

Troubleshooting Common Issues with Interactive WordPress Blocks

The block doesn’t respond to clicks

Check that viewScriptModule is set in block.json , not viewScript. The Interactivity API requires ES module loading. Using the wrong key silently breaks everything.

State doesn’t update between multiple block instances

Use data-wp-context on each block wrapper to isolate state per instance. Don’t rely solely on global state in store() for per-block values.

data-wp-bind–hidden doesn’t work as expected

The hidden HTML attribute is boolean. Make sure your context value is strictly true or false, not a string like "false". A string value of "false" still evaluates as truthy in HTML.

Build errors after scaffolding

Make sure your Node.js version is 18 or higher. Run node -v to check. Older versions cause silent failures with the @wordpress/scripts package.

The view.js file isn’t loading on the front end

Confirm WordPress 6.5+ is running. The Script Modules API that powers viewScriptModule wasn’t available in earlier versions. You can verify your version in Dashboard → Updates. Also check the WordPress Interactivity API reference documentation for version-specific notes.

Conclusion

You now know how to build interactive WordPress blocks using the WordPress Interactivity API and data-wp- directives. You scaffolded a block plugin, defined reactive state with store(), and wired up click events and DOM bindings using declarative HTML attributes. This approach keeps your blocks performant and maintainable. You’re not shipping a full React app , just clean, scoped interactivity where you need it. From here, you can explore more advanced directives like data-wp-each for rendering lists, or data-wp-watch for running side effects when state changes. The Interactivity API is still evolving fast, so keep an eye on the official WordPress developer blog for new features and updates.

Similar Posts