Goal
Add interactivity to store blocks without jQuery and without your own React bundle on the frontend.
Key concepts
- Interactivity API — the WordPress standard for frontend interactivity (
data-wp-*directives in HTML) viewScriptModuleinblock.json— JS as an ES module, loaded only where the block isstore()— state, actions and callbacks;wp_interactivity_state()— initial state from PHP- Directives:
data-wp-interactive,data-wp-context,data-wp-on--click,data-wp-text,data-wp-bind--disabled - Server render + hydration: the HTML is correct even before the JS loads
- WooCommerce blocks (for example, the product button in a collection) use the Interactivity API too
Diagram
sequenceDiagram
participant PHP as render.php
participant H as HTML with data-wp-*
participant JS as view.js (store)
participant API as Store API
PHP->>H: state and context
H->>JS: hydration
JS->>API: POST /cart/add-item
API-->>JS: cart
JS->>H: update the text and the button state
Code
render.php — a "Quick add" button:
<?php
$product = wc_get_product( $block->context['postId'] ?? 0 );
if ( ! $product || ! $product->is_purchasable() || ! $product->is_in_stock() ) {
return;
}
wp_interactivity_state( 'my/quick-add', [
'nonce' => wp_create_nonce( 'wc_store_api' ),
] );
$context = [ 'productId' => $product->get_id(), 'loading' => false, 'added' => false ];
?>
<div <?php echo get_block_wrapper_attributes(); ?>
data-wp-interactive="my/quick-add"
<?php echo wp_interactivity_data_wp_context( $context ); ?>>
<button type="button"
data-wp-on--click="actions.add"
data-wp-bind--disabled="context.loading">
<span data-wp-text="state.label"><?php esc_html_e( 'Quick add', 'my-plugin' ); ?></span>
</button>
</div>
view.js:
import { store, getContext } from '@wordpress/interactivity';
const { state } = store( 'my/quick-add', {
state: {
get label() {
const ctx = getContext();
if ( ctx.loading ) return 'Adding…';
return ctx.added ? 'In cart ✓' : 'Quick add';
},
},
actions: {
*add() {
const ctx = getContext();
ctx.loading = true;
try {
const res = yield fetch( '/wp-json/wc/store/v1/cart/add-item', {
method: 'POST',
headers: { 'Content-Type': 'application/json', Nonce: state.nonce },
body: JSON.stringify( { id: ctx.productId, quantity: 1 } ),
} );
ctx.added = res.ok;
} finally {
ctx.loading = false;
}
},
},
} );
In block.json:
{
"supports": { "interactivity": true },
"viewScriptModule": "file:./view.js"
}
Common mistakes
| Symptom | Cause | Fix |
|---|---|---|
| Directives don't work | No supports.interactivity or viewScriptModule | Add both to block.json |
| The Mini-Cart counter didn't update after adding | A separate request doesn't notify WooCommerce blocks | Use the WooCommerce cart store API or refresh the Mini-Cart with an event; check for your version |
| An async action doesn't update the state | async/await instead of a generator | Async actions are written as generators *add() with yield |
Weak and strong answer
Question: How do you build a "Quick add" button in a product card?
Weak answer. I'll attach jQuery to the click and make an AJAX call to admin-ajax.php.
Strong answer. A block with the Interactivity API: a server-rendered button, a context with the product ID, an action that calls the Store API
cart/add-itemwith a Nonce. The script is a module, loaded only with the block, no jQuery. Separately I check that the Mini-Cart updates too.
Why the second is stronger: A modern stack, the Store API instead of admin-ajax and attention to UI consistency.
Practice
Add a "Quick add" button on the Interactivity API to your badge from lesson 5.2. Show the "Adding…" and "In cart" states. Check in DevTools that the block's JS doesn't load on pages without it.
Interview Questions
The WordPress standard for frontend interactivity: the server renders HTML with data-wp-* directives, and a small runtime binds them to a JS store. Blocks on the same page can share state.
No duplicated markup on the client, it works with server rendering, and the scripts are modules loaded only with the block. State can be passed from PHP through wp_interactivity_state().
wp_interactivity_state( 'namespace', [...] ) — global state; wp_interactivity_data_wp_context() — the local context of a specific block.