Interactieve componenten bouwen
WordPress-blokken zijn standaard statisch. De editor slaat HTML op in de database, de frontend rendert het en daarmee is het verhaal afgelopen. Voor veel blokken is dat precies goed. Maar sommige componenten moeten reageren op gebruikersinteractie: inhoud in- en uitklappen, tussen tabbladen wisselen, dialogen openen en tellers bijwerken.
De WordPress Interactivity API voegt reactief gedrag aan de clientzijde toe aan blokken met HTML-attributen die directives worden genoemd. Je schrijft data-wp-on--click in plaats van addEventListener, data-wp-bind--hidden in plaats van element.hidden = true. De API regelt reactiviteit, contextisolatie en hydratatie automatisch.
Blockstudio regelt de bedrading. Stel "interactivity": true in je block.json in, en Blockstudio genereert de importmap, laadt de API in zowel de editor als de frontend en lost je ES-module-imports op. Geen buildstap, geen bundler, geen webpack-configuratie. Raadpleeg de Interactivity-referentie voor configuratiedetails.
Deze gids behandelt vier complete componenten, die elk nieuwe concepten introduceren. Aan het einde heb je werkende patronen voor de meest voorkomende interactieve UI-elementen.
Hoe het werkt
Directives
Directives zijn data-wp-*-attributen die reactief gedrag rechtstreeks in je HTML declareren. De meest gebruikte zijn:
| Directive | Doel | Voorbeeld |
|---|---|---|
data-wp-interactive |
De naamruimte van de store definiëren | data-wp-interactive="myBlock" |
data-wp-context |
Lokale reactieve status per instantie | data-wp-context='{ "isOpen": false }' |
data-wp-on--[event] |
Event-handler | data-wp-on--click="actions.toggle" |
data-wp-bind--[attr] |
Een HTML-attribuut binden | data-wp-bind--hidden="!context.isOpen" |
data-wp-class--[name] |
Een CSS-class in- of uitschakelen | data-wp-class--is-active="context.isActive" |
data-wp-text |
Tekstinhoud instellen | data-wp-text="state.count" |
data-wp-style--[prop] |
Een inline-stijl instellen | data-wp-style--opacity="context.opacity" |
data-wp-on-document--[event] |
Globaal documentevent | data-wp-on-document--keydown="actions.onKeydown" |
data-wp-watch |
Een callback uitvoeren wanneer de status verandert | data-wp-watch="callbacks.log" |
data-wp-each |
Een array doorlopen | data-wp-each="state.items" |
De store
Elk interactief blok heeft een store, die je maakt door store() aan te roepen met een naamruimte en een object met actions, callbacks en optioneel state:
import { store, getContext } from '@wordpress/interactivity';
store('myBlock', {
actions: {
toggle: () => {
const context = getContext();
context.isOpen = !context.isOpen;
},
},
});
In actions retourneert getContext() het dichtstbijzijnde data-wp-context-object hoger in de DOM-boom. getElement() retourneert een verwijzing naar het DOM-element dat de action heeft geactiveerd, handig om data-*-attributen uit te lezen.
Context versus status
Context (data-wp-context) is lokaal voor elke blokinstantie. Als je drie accordeons op een pagina plaatst, heeft elke accordeon zijn eigen waarde voor isOpen. Het omschakelen van de ene accordeon heeft geen invloed op de andere.
Status (wp_interactivity_state()) is globaal en wordt gedeeld door alle instanties van een blok. Gebruik dit voor gegevens van de server, zoals een aantal reacties, of voor waarden die overal gelijk moeten zijn.
Context werkt zowel in de editor als op de frontend. Status werkt alleen op de frontend, omdat WordPress deze serialiseert naar een script-tag die niet is opgenomen in editor-REST-API-reacties.
Accordeon
Het eenvoudigste interactieve patroon: klik op een knop en klap inhoud in of uit. Dit voorbeeld heeft slechts drie directives en een paar regels JavaScript nodig.
{
"name": "my-theme/accordion",
"title": "Accordion",
"category": "text",
"icon": "arrow-down-alt2",
"description": "Expandable content section.",
"blockstudio": {
"interactivity": true,
"attributes": [
{ "id": "heading", "type": "text", "label": "Heading", "default": "Accordion heading" },
{ "id": "body", "type": "textarea", "label": "Body", "default": "Accordion content goes here." }
]
}
}
<div useBlockProps
data-wp-interactive="myTheme/accordion"
data-wp-context='{ "isOpen": false }'>
<button
data-wp-on--click="actions.toggle"
data-wp-bind--aria-expanded="context.isOpen"
aria-controls="accordion-panel"
style="all: unset; cursor: pointer; display: flex; justify-content: space-between; align-items: center; width: 100%; padding: 1rem; font-weight: 600; font-size: 1.125rem;">
<?php echo esc_html( $a['heading'] ); ?>
<span aria-hidden="true" data-wp-text="context.isOpen ? '−' : '+'">+</span>
</button>
<div
id="accordion-panel"
role="region"
data-wp-bind--hidden="!context.isOpen"
style="padding: 0 1rem 1rem;">
<p><?php echo esc_html( $a['body'] ); ?></p>
</div>
</div>
import { store, getContext } from '@wordpress/interactivity';
store('myTheme/accordion', {
actions: {
toggle: () => {
const context = getContext();
context.isOpen = !context.isOpen;
},
},
});
Zo werkt het:
data-wp-context='{ "isOpen": false }'maakt een lokale booleanwaarde voor deze instantie aan.- Als je op de knop klikt, wordt
actions.toggleaangeroepen, diecontext.isOpenomschakelt. data-wp-bind--hidden="!context.isOpen"verbergt of toont het paneel.data-wp-bind--aria-expandedendata-wp-textwerken de knopstatus bij voor toegankelijkheid en de visuele indicator.
Omdat elke blokinstantie een eigen context krijgt, werken meerdere accordeons op een pagina direct. Ze schakelen onafhankelijk van elkaar om.
Tabbladen
Tabbladen introduceren twee nieuwe concepten: data-wp-class--* om CSS-classes in of uit te schakelen, en getElement() om data-attributen uit te lezen van het element dat een action heeft geactiveerd.
Dit voorbeeld gebruikt een repeaterveld, zodat redacteuren zoveel tabbladen kunnen toevoegen als ze nodig hebben.
{
"name": "my-theme/tabs",
"title": "Tabs",
"category": "text",
"icon": "table-row-after",
"description": "Tabbed content switcher.",
"blockstudio": {
"interactivity": true,
"attributes": [
{
"id": "tabs",
"type": "repeater",
"label": "Tabs",
"min": 1,
"max": 8,
"attributes": [
{ "id": "label", "type": "text", "label": "Tab Label", "default": "Tab" },
{ "id": "content", "type": "textarea", "label": "Content", "default": "Tab content goes here." }
]
}
]
}
}
<div useBlockProps
data-wp-interactive="myTheme/tabs"
data-wp-context='{ "activeTab": 0 }'>
<div role="tablist" style="display: flex; gap: 0; border-bottom: 2px solid #e5e7eb;">
<?php foreach ( $a['tabs'] as $i => $tab ) : ?>
<button
role="tab"
data-index="<?php echo esc_attr( $i ); ?>"
data-wp-on--click="actions.selectTab"
data-wp-class--is-active-tab="callbacks.isActiveTab"
data-wp-bind--aria-selected="callbacks.isActiveTab"
style="padding: 0.75rem 1.5rem; background: none; border: none; cursor: pointer; font-weight: 500; border-bottom: 2px solid transparent; margin-bottom: -2px;">
<?php echo esc_html( $tab['label'] ); ?>
</button>
<?php endforeach; ?>
</div>
<?php foreach ( $a['tabs'] as $i => $tab ) : ?>
<div
role="tabpanel"
data-index="<?php echo esc_attr( $i ); ?>"
data-wp-bind--hidden="!callbacks.isActiveTab"
style="padding: 1.5rem 0;">
<p><?php echo esc_html( $tab['content'] ); ?></p>
</div>
<?php endforeach; ?>
</div>
import { store, getContext, getElement } from '@wordpress/interactivity';
store('myTheme/tabs', {
actions: {
selectTab: () => {
const context = getContext();
const { ref } = getElement();
context.activeTab = parseInt(ref.dataset.index, 10);
},
},
callbacks: {
isActiveTab: () => {
const context = getContext();
const { ref } = getElement();
return context.activeTab === parseInt(ref.dataset.index, 10);
},
},
});
.is-active-tab {
border-bottom-color: currentColor !important;
color: var(--wp--preset--color--primary, #111);
}
Wat is hier nieuw:
getElement()retourneert{ ref }, waarinrefhet DOM-element is. We lezendata-indexuit om te weten welk tabblad is aangeklikt. Zo hoef je geen aparte action voor elk tabblad te maken.callbackszijn afgeleide waarden die opnieuw worden geëvalueerd wanneer de context verandert. Zowel de tabbladknoppen als de panelen gebruikencallbacks.isActiveTabom te controleren of hun index overeenkomt metcontext.activeTab.data-wp-class--is-active-tabvoegt deis-active-tab-class toe of verwijdert deze op basis van de geretourneerde callbackwaarde.
Modal
De modal introduceert eventafhandeling op documentniveau met data-wp-on-document--keydown om te sluiten met Escape, en sluiten door op de achtergrond te klikken. Ook worden de juiste toegankelijkheidsattributen voor dialogen gedemonstreerd.
{
"name": "my-theme/modal",
"title": "Modal",
"category": "text",
"icon": "external",
"description": "Button that opens a modal dialog.",
"blockstudio": {
"interactivity": true,
"attributes": [
{ "id": "buttonText", "type": "text", "label": "Button Text", "default": "Open Modal" },
{ "id": "title", "type": "text", "label": "Modal Title", "default": "Modal Title" },
{ "id": "body", "type": "textarea", "label": "Modal Body", "default": "Modal content goes here." }
]
}
}
<div useBlockProps
data-wp-interactive="myTheme/modal"
data-wp-context='{ "isOpen": false }'>
<button
data-wp-on--click="actions.open"
style="padding: 0.75rem 1.5rem; background: #111; color: #fff; border: none; border-radius: 6px; cursor: pointer; font-size: 1rem;">
<?php echo esc_html( $a['buttonText'] ); ?>
</button>
<div
data-wp-bind--hidden="!context.isOpen"
data-wp-on--click="actions.backdropClick"
data-wp-on-document--keydown="actions.onKeydown"
style="position: fixed; inset: 0; z-index: 9999; display: flex; align-items: center; justify-content: center; background: rgba(0,0,0,0.5);">
<div
role="dialog"
aria-modal="true"
data-wp-bind--aria-label="context.isOpen ? '<?php echo esc_attr( $a['title'] ); ?>' : false"
data-wp-on--click="actions.stopPropagation"
style="background: #fff; border-radius: 12px; padding: 2rem; max-width: 32rem; width: 100%; margin: 1rem; position: relative;">
<h2 style="margin: 0 0 1rem; font-size: 1.25rem;"><?php echo esc_html( $a['title'] ); ?></h2>
<p style="margin: 0 0 1.5rem; color: #555;"><?php echo esc_html( $a['body'] ); ?></p>
<button
data-wp-on--click="actions.close"
style="padding: 0.5rem 1rem; background: #f3f4f6; border: none; border-radius: 6px; cursor: pointer;">
Close
</button>
</div>
</div>
</div>
import { store, getContext } from '@wordpress/interactivity';
store('myTheme/modal', {
actions: {
open: () => {
const context = getContext();
context.isOpen = true;
},
close: () => {
const context = getContext();
context.isOpen = false;
},
backdropClick: () => {
const context = getContext();
context.isOpen = false;
},
stopPropagation: (event) => {
event.stopPropagation();
},
onKeydown: (event) => {
if (event.key === 'Escape') {
const context = getContext();
context.isOpen = false;
}
},
},
});
Wat is hier nieuw:
data-wp-on-document--keydownluistert naardocumentin plaats van naar het element zelf. De handler wordt geactiveerd ongeacht welk element de focus heeft, zodat Escape overal werkt.- Sluiten door op de achtergrond te klikken gebruikt twee lagen: de overlay-div roept
actions.backdropClickaan, terwijl de interne dialoogactions.stopPropagationaanroept om te voorkomen dat klikken in de dialoog deze sluiten. role="dialog"enaria-modal="true"laten schermlezers weten dat dit een modale dialoog is.aria-labelis gebonden, zodat het alleen wordt toegepast wanneer de modal zichtbaar is.- Het attribuut
hiddenop de overlay verbergt de modal en voorkomt dat de documentlistener voor keydown wordt geactiveerd wanneer de modal gesloten is, omdat directives op verborgen elementen worden gepauzeerd.
Like-knop met serverstatus
Dit voorbeeld combineert status aan de serverzijde met actions aan de clientzijde. Het aantal likes wordt geïnitialiseerd vanuit PHP met wp_interactivity_state(), en de knop werkt het bij wanneer erop wordt geklikt.
{
"name": "my-theme/like-button",
"title": "Like Button",
"category": "text",
"icon": "heart",
"description": "A like button with a count.",
"blockstudio": {
"interactivity": true,
"attributes": [
{ "id": "itemId", "type": "text", "label": "Item ID", "default": "post-1" }
]
}
}
<?php
$item_id = $a['itemId'];
$count = (int) get_option( "likes_{$item_id}", 0 );
wp_interactivity_state( 'myTheme/likeButton', array(
'count' => $count,
) );
?>
<div useBlockProps
data-wp-interactive="myTheme/likeButton"
data-wp-context='{ "liked": false }'>
<button
data-wp-on--click="actions.like"
data-wp-class--is-liked="context.liked"
style="display: inline-flex; align-items: center; gap: 0.5rem; padding: 0.5rem 1rem; border: 2px solid #e5e7eb; border-radius: 999px; background: none; cursor: pointer; font-size: 1rem; transition: all 0.2s;">
<span data-wp-text="context.liked ? '❤️' : '🤍'">🤍</span>
<span data-wp-text="state.count"><?php echo esc_html( $count ); ?></span>
</button>
</div>
import { store, getContext } from '@wordpress/interactivity';
const { state } = store('myTheme/likeButton', {
actions: {
like: () => {
const context = getContext();
if (context.liked) {
context.liked = false;
state.count--;
} else {
context.liked = true;
state.count++;
}
},
},
});
.is-liked {
border-color: #ef4444 !important;
background: #fef2f2 !important;
}
Wat is hier nieuw:
wp_interactivity_state()initialiseert het aantal vanuit PHP. De waarde wordt geserialiseerd naar de HTML van de pagina en is beschikbaar alsstate.countin directives en JavaScript.stateversuscontext: het aantal staat instate(globaal, gedeeld), terwijllikedincontextstaat (per instantie). Als je meerdere like-knoppen voor hetzelfde item had, zouden ze het aantal delen, maar kon elke knop de eigen like-status bijhouden.- Destructureren uit
store(): de aanroepstore()retourneert een reactiefstate-object waarnaar je in je actions kunt verwijzen.
Belangrijke kanttekening: serverstatus is alleen beschikbaar op de frontend. In de editor wordt het blok gerenderd via de REST API, dus wp_interactivity_state() is niet opgenomen. De terugvaltekst die door PHP wordt gerenderd (<?php echo esc_html( $count ); ?>) wordt als beginwaarde getoond in het editorvoorbeeld. Gebruik data-wp-context voor een status die interactief is in de editor.
Tips en patronen
Conventies voor naamruimten. Gebruik de naam van je theme of plugin als voorvoegsel: myTheme/accordion, myPlugin/tabs. Zo voorkom je conflicten wanneer meerdere blokken op dezelfde pagina de Interactivity API gebruiken.
Geen buildstap nodig. Blockstudio laadt script.js als native ES-module en genereert automatisch de importmap voor @wordpress/interactivity. Je schrijft standaard JavaScript met import-instructies en het werkt meteen.
Blokken met alleen directives. Als je blok alleen data-wp-context met data-wp-bind--hidden of data-wp-text gebruikt, heb je helemaal geen script.js nodig. De Interactivity API verwerkt dit declaratief. Het accordeonvoorbeeld hierboven zou zonder JavaScript kunnen werken als je een checkboxtruc gebruikte, maar de scriptbenadering is netter.
Fouten opsporen met data-wp-watch. Voeg een watch-callback toe om tijdens de ontwikkeling contextwijzigingen te loggen:
store('myBlock', {
callbacks: {
debug: () => {
const context = getContext();
console.log('context changed:', { ...context });
},
},
});
<div data-wp-watch="callbacks.debug" ...>
Verwijder deze vóór publicatie.
Houd de context beperkt. Zet alleen waarden in data-wp-context die daadwerkelijk veranderen. Statische gegevens, zoals labels en inhoud, horen in PHP te blijven. De context-JSON wordt naar elke instantie van het blok geserialiseerd, dus grote objecten maken de pagina zwaarder.
Volgende stappen
- Interactivity-referentie: configuratieopties, details over editorondersteuning en de objectvorm van de instelling
interactivity. - Assets: hoe Blockstudio
script.js,style.cssen andere blokassets laadt. - WordPress Interactivity API-documentatie: de volledige referentie voor API, waaronder
data-wp-each,data-wp-init,data-wp-runen andere directives die niet in deze gids worden behandeld.