WordPress Interactivity API

About

Since version 6.5, the Interactivity API is a part of WordPress. It's a standard system of directives, based on declarative code, for adding front-end interactivity to blocks. Similar to React or Vue, it offers a declarative approach and provides server-side rendering out-of-the-box.

If you're new to the WordPress Interactivity API, we recommend reading a detailed explanation on our blog.

View and Card templates fully support it, meaning you can use any directives in any template, regardless of the render method (shortcode or Gutenberg block).

Example of usage:

For Twig: custom.twig

{{ wp_interactivity_state('my-unique-name', {
  isHidden: false,
}) }}
<div data-wp-interactivity="my-unique-name"
     data-wp-context="{{ {'postId': _view.object_id }|json_encode }}">
  <div data-wp-bind--hidden="state.isHidden">
    My post id is <span data-wp-text="context.postId"></span>
  </div>
  <button data-wp-on--click="actions.toggle">Toggle</button>
</div>

For Blade: custom.blade.php

@php wp_interactivity_state('my-unique-name', {
  isHidden: false,
}) @endphp
<div data-wp-interactivity="my-unique-name"
      {!! wp_interactivity_data_wp_context(["postId" => $_view.object_id,]) !!}
  <div data-wp-bind--hidden="state.isHidden">
    My post id is <span data-wp-text="context.postId"></span>
  </div>
  <button data-wp-on--click="actions.toggle">Toggle</button>
</div>

script.js

import { getContext, store } from '@wordpress/interactivity';

const { state } = store('my-unique-name', {
  actions: {
    toggle: () => {
      state.isHidden = !state.isHidden;
      console.log('Toggled state for ' + getContext().postId);
    }
  }
});

Notes

1. WebComponent type setting

If you're using the WP Interactivity API, the webComponent type setting of the target View or Card must be set to 'None'. This means you must choose either WP Interactivity or WebComponent, as you can't use both at once. Otherwise, the JS code won't be added as-is but will be wrapped into a web component, causing the top import to fail.

2. Interactivity API Basics

2.1) Block name

To use the WP Interactivity API, you should add data-wp-interactivity='x' to the top tag of your element. The name can be any, but we recommend using the View or Card name or ID.

2.2) Context

Using data-wp-context, you can declare any variables of the template as context, which will be used in directives and available in the JS code. Don't forget to use the Twig json_encode filter to turn the object into a string, as shown in the example.

2.3) State

Using the wp_interactivity_state function, you can declare any variables of the template as state, which will be used in directives and available in JS code. This function must be called before the data-wp-interactivity attribute, so you should place it above the top tag of your template. Check the WP documentation to understand the difference between state and context.

Note: While you can't call any WP function directly in Twig, the wp_interactivity_state function is 'mirrored' by AVF, making it available in any Twig template. This function calls the WP function behind the scenes. Read more about our Twig integration here.

2.3) @wordpress/interactivity Package

WP Interactivity employs modules, which are already supported in all modern browsers. The @wordpress/interactivity package is an alias for the built-in WP interactivity script, which will be enqueued as a module automatically, so you don't need to worry about manual enqueueing in your theme.

2.4) Server Side Rendering

The directives will initially be processed on the server side. For example, if you change the isHidden state to true, the div with the hidden bind will have the hidden attribute inside the HTML, so the client won't wait until the JS executes to hide that div.

WP also takes care of hydration/rehydration, keeping everything in sync when you change state or context in the JS code during client-side execution as well.