Ga naar de inhoud

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:

JavaScript
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.

JSON
{
  "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." }
    ]
  }
}
PHP
<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>
JavaScript
import { store, getContext } from '@wordpress/interactivity';

store('myTheme/accordion', {
  actions: {
    toggle: () => {
      const context = getContext();
      context.isOpen = !context.isOpen;
    },
  },
});

Zo werkt het:

  1. data-wp-context='{ "isOpen": false }' maakt een lokale booleanwaarde voor deze instantie aan.
  2. Als je op de knop klikt, wordt actions.toggle aangeroepen, die context.isOpen omschakelt.
  3. data-wp-bind--hidden="!context.isOpen" verbergt of toont het paneel.
  4. data-wp-bind--aria-expanded en data-wp-text werken 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.

JSON
{
  "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." }
        ]
      }
    ]
  }
}
PHP
<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>
JavaScript
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);
    },
  },
});
CSS
.is-active-tab {
  border-bottom-color: currentColor !important;
  color: var(--wp--preset--color--primary, #111);
}

Wat is hier nieuw:

  • getElement() retourneert { ref }, waarin ref het DOM-element is. We lezen data-index uit om te weten welk tabblad is aangeklikt. Zo hoef je geen aparte action voor elk tabblad te maken.
  • callbacks zijn afgeleide waarden die opnieuw worden geëvalueerd wanneer de context verandert. Zowel de tabbladknoppen als de panelen gebruiken callbacks.isActiveTab om te controleren of hun index overeenkomt met context.activeTab.
  • data-wp-class--is-active-tab voegt de is-active-tab-class toe of verwijdert deze op basis van de geretourneerde callbackwaarde.

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.

JSON
{
  "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." }
    ]
  }
}
PHP
<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>
JavaScript
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--keydown luistert naar document in 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.backdropClick aan, terwijl de interne dialoog actions.stopPropagation aanroept om te voorkomen dat klikken in de dialoog deze sluiten.
  • role="dialog" en aria-modal="true" laten schermlezers weten dat dit een modale dialoog is. aria-label is gebonden, zodat het alleen wordt toegepast wanneer de modal zichtbaar is.
  • Het attribuut hidden op 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.

JSON
{
  "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
<?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>
JavaScript
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++;
      }
    },
  },
});
CSS
.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 als state.count in directives en JavaScript.
  • state versus context: het aantal staat in state (globaal, gedeeld), terwijl liked in context staat (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 aanroep store() retourneert een reactief state-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:

JavaScript
store('myBlock', {
  callbacks: {
    debug: () => {
      const context = getContext();
      console.log('context changed:', { ...context });
    },
  },
});
HTML
<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.css en andere blokassets laadt.
  • WordPress Interactivity API-documentatie: de volledige referentie voor API, waaronder data-wp-each, data-wp-init, data-wp-run en andere directives die niet in deze gids worden behandeld.