Lesson 5.3. Interactivity API

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)
  • viewScriptModule in block.json — JS as an ES module, loaded only where the block is
  • store() — 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
<?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:

JAVASCRIPT
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:

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

Common mistakes

SymptomCauseFix
Directives don't workNo supports.interactivity or viewScriptModuleAdd both to block.json
The Mini-Cart counter didn't update after addingA separate request doesn't notify WooCommerce blocksUse the WooCommerce cart store API or refresh the Mini-Cart with an event; check for your version
An async action doesn't update the stateasync/await instead of a generatorAsync 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-item with 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.

Save your progress

Sign in or create a free account to mark lessons as completed and continue the whole course. You will come back to this lesson.