Menu
Build interactive blocks using WordPress Interactivity API. Covers data-wp-* directives, stores, context management, and server-side rendering patterns. Use when adding client-side interactivity to blocks without a full JavaScript framework.
| name | 10up-interactivity-api |
| description | Build interactive blocks using WordPress Interactivity API. Covers data-wp-* directives, stores, context management, and server-side rendering patterns. Use when adding client-side interactivity to blocks without a full JavaScript framework. |
| license | MIT |
| compatibility | WordPress 6.5+, PHP 8.0+, requires viewScriptModule support |
| globs | ["**/view.js","**/view.ts","blocks/**/*","includes/blocks/**/*"] |
| metadata | {"author":"10up","version":"1.0"} |
This skill guides you through building interactive blocks using the WordPress Interactivity API, a lightweight reactive system for block-based interactivity.
The Interactivity API provides:
data-wp-*){
"name": "tenup/accordion",
"supports": {
"interactivity": true
},
"viewScriptModule": "file:./view.js"
}
Important: Use viewScriptModule (ES module), not viewScript (classic script).
Create the store with state, actions, and callbacks:
import { store, getContext } from '@wordpress/interactivity';
const { state, actions } = store('tenup/accordion', {
state: {
// Global state (shared across all instances)
get isAnyOpen() {
return Object.values(state.items).some(item => item.isOpen);
}
},
actions: {
toggle() {
const context = getContext();
context.isOpen = !context.isOpen;
},
open() {
const context = getContext();
context.isOpen = true;
},
close() {
const context = getContext();
context.isOpen = false;
}
},
callbacks: {
onInit() {
const context = getContext();
// Runs when element with data-wp-init mounts
console.log('Accordion initialized:', context.id);
}
}
});
<?php
/**
* Accordion block markup
*/
$accordion_id = wp_unique_id('accordion-');
$is_open = $attributes['defaultOpen'] ?? false;
// Set up interactivity context
$context = [
'id' => $accordion_id,
'isOpen' => $is_open,
];
$wrapper_attributes = get_block_wrapper_attributes([
'data-wp-interactive' => 'tenup/accordion',
'data-wp-context' => wp_json_encode($context),
]);
?>
<div <?php echo $wrapper_attributes; ?>>
<button
data-wp-on--click="actions.toggle"
data-wp-bind--aria-expanded="context.isOpen"
aria-controls="<?php echo esc_attr($accordion_id); ?>-content"
>
<?php echo esc_html($attributes['title'] ?? 'Toggle'); ?>
</button>
<div
id="<?php echo esc_attr($accordion_id); ?>-content"
data-wp-bind--hidden="!context.isOpen"
data-wp-class--is-open="context.isOpen"
>
<?php echo $content; // phpcs:ignore ?>
</div>
</div>
| Directive | Purpose | Example |
|---|---|---|
data-wp-interactive | Mark interactive region and namespace | data-wp-interactive="tenup/accordion" |
data-wp-context | Provide scoped state (JSON) | data-wp-context='{"isOpen":false}' |
data-wp-on--{event} | Event handler | data-wp-on--click="actions.toggle" |
data-wp-bind--{attr} | Bind attribute to state | data-wp-bind--hidden="!context.isOpen" |
data-wp-class--{name} | Toggle CSS class | data-wp-class--is-active="context.isActive" |
data-wp-text | Set text content | data-wp-text="context.label" |
data-wp-init | Run on mount | data-wp-init="callbacks.onInit" |
data-wp-watch | React to state changes | data-wp-watch="callbacks.onStateChange" |
See references/directives.md for complete reference.
For complex initial state, use wp_interactivity_state():
// In your block's render callback or plugin
wp_interactivity_state('tenup/accordion', [
'items' => [],
'allowMultiple' => true,
]);
This merges with client-side store state.
Context flows down the DOM tree:
<div data-wp-interactive="tenup/tabs" data-wp-context='{"activeTab":0}'>
<!-- Child elements can access context.activeTab -->
<button data-wp-on--click="actions.setTab" data-wp-context='{"tabIndex":0}'>
<!-- This element has both activeTab and tabIndex in context -->
</button>
</div>
Access nested context in actions:
actions: {
setTab() {
const context = getContext();
// context.tabIndex is from the button
// context.activeTab is from the parent
context.activeTab = context.tabIndex;
}
}
<button
data-wp-on--click="actions.toggle"
data-wp-bind--aria-pressed="context.isActive"
>
Toggle
</button>
actions: {
toggle() {
const context = getContext();
context.isActive = !context.isActive;
}
}
<div data-wp-bind--hidden="!context.isVisible">
Content
</div>
<div
data-wp-class--is-open="context.isOpen"
data-wp-class--is-animating="state.isAnimating"
>
<button
data-wp-on--click="actions.handleClick"
data-wp-on--keydown="actions.handleKeydown"
data-wp-on--focus="actions.handleFocus"
>
state: {
items: [],
get count() {
return state.items.length;
},
get isEmpty() {
return state.items.length === 0;
}
}
After implementing interactivity:
npm run build"Nothing happens on click":
data-wp-interactive is on ancestor elementviewScriptModule is in block.json"Context is undefined":
data-wp-context on element or ancestor"State doesn't update":
getContext() for instance statedata-wp-bind--*)"Works in dev, fails in production":
See references/debugging.md for troubleshooting.
Ask the user when:
Create and modify Gutenberg blocks following 10up engineering standards. Covers block.json metadata, dynamic rendering with PHP, attributes, deprecations, editor components, and the useBlockProps pattern. Use when creating new blocks, fixing block errors, or modifying existing block code.
Extend core WordPress blocks with custom attributes and controls using the 10up block extension pattern. Alternative to block styles when multiple controls are needed. Use when adding functionality to existing blocks rather than creating new ones.
Create reusable block patterns and synced patterns following 10up standards. Covers PHP file-based registration, pattern metadata, categories, and the block bindings API. Use when creating reusable layout components or content templates.
Build and modify WordPress block themes following 10up standards. Covers theme.json configuration, templates, template parts, patterns, style variations, and CSS organization. Use when working on block-based themes or Site Editor customizations.
Write clear, consistent commit messages following 10up conventions. Uses conventional commit style with lowercase formatting. Use when creating commits, writing PR descriptions, or generating changelogs.
CSS architecture, best practices, and patterns for WordPress projects. Covers ITCSS methodology, accessibility, specificity management, naming conventions, and modern CSS features.