Unleash the power of the Interactivity API

What do we need an
Interactivity API for?

Requirements

• Code editor (VS Code)
• Node.js development tools
• Local WordPress development environment

Getting started from scratch…

@wordpress/create-block Interactivity API template for scaffolding

npx @wordpress/create-block@latest my-first-interactive-block --template @wordpress/create-block-interactive-template

cd my-first-interactive-block && npm start

What are directives?

Directives: custom attributes that are added to the markup of your block to add behavior to its DOM elements. Interactivity API directives use the data-wp- prefix.

<div
  data-wp-interactive="myPlugin"
  data-wp-context='{ "isOpen": false }'
  data-wp-watch="callbacks.logIsOpen"
>
  <button
    data-wp-on--click="actions.toggle"
    data-wp-bind--aria-expanded="context.isOpen"
    aria-controls="p-1"
  >
    Toggle
  </button>

  <p id="p-1" data-wp-bind--hidden="!context.isOpen">
    This element is now visible!
  </p>
</div>

Directives can also be injected dynamically using the HTML Tag Processor.

List of directives

wp-interactive*

“Activates” the interactivity for the DOM element and its children through the Interactivity API (directives and store).

<!-- Let's make this element and its children interactive and set the namespace -->
<div
  data-wp-interactive="myPlugin"
  data-wp-context='{ "myColor" : "red", "myBgColor": "yellow" }'
>
  <p>I'm interactive now, <span data-wp-style--background-color="context.myBgColor">and I can use directives!</span></p>
  <div>
    <p>I'm also interactive, <span data-wp-style--color="context.myColor">and I can also use directives!</span></p>
  </div>
</div>

<!-- Let's make this element and its children interactive and set the namespace -->
<div
  data-wp-interactive='{ "namespace": "myPlugin" }'
  data-wp-context='{ "myColor" : "red", "myBgColor": "yellow" }'
>
  <p>I'm interactive now, <span data-wp-style--background-color="context.myBgColor">and I can use directives!</span></p>
  <div>
    <p>I'm also interactive, <span data-wp-style--color="context.myColor">and I can also use directives!</span></p>
  </div>
</div>

wp-context*

It provides a local state available to a specific HTML node and its children.

The wp-context directive accepts a stringified JSON as a value.

<div data-wp-context='{ "post": { "id": <?php echo $post->ID; ?> } }'>
  <button data-wp-on--click="actions.logId">
    Click Me!
  </button>
</div>

store( "myPlugin", {
  actions: {
    logId: () => {
      const { post } = getContext();
      console.log( post.id );
    },
  },
} );

wp-context* – nesting

Different contexts can be defined at different levels, and deeper levels will merge their context with any parent one:

<div data-wp-context="{ foo: 'bar' }">
  <span data-wp-text="context.foo"><!-- Will output: "bar" --></span>

  <div data-wp-context="{ bar: 'baz' }">
    <span data-wp-text="context.foo"><!-- Will output: "bar" --></span>

    <div data-wp-context="{ foo: 'bob' }">
      <span data-wp-text="context.foo"><!-- Will output: "bob" --></span>
    </div>

  </div>
</div>

The store

The store is used to create the logic (actions, side effects, etc.) linked to the directives and the data used inside that logic (state, derived state, etc.).

The store is usually created in the view.js file of each block, although the state can be initialized from the render.php of the block.

Elements of the store

• State
  • Global state
  • Context / local state
• Actions
• Side effects
• Derived state

State

It defines data available to the HTML nodes of the page. It is important to differentiate between two ways to define the data:

• Global state: It is defined using the store() function with the state property, and the data is available to all the HTML nodes of the page.
• Context/Local State: It is defined using the data-wp-context directive in an HTML node, and the data is available to that HTML node and its children. It can be accessed using the getContext function inside of an action, derived state or side effect.

<div data-wp-context='{ "someText": "Hello World!" }'>

  <!-- Access global state -->
  <span data-wp-text="state.someText"></span>

  <!-- Access local state (context) -->
  <span data-wp-text="context.someText"></span>

</div>

const { state } = store( "myPlugin", {
  state: {
    someText: "Hello Universe!"
  },
  actions: {
    someAction: () => {
      state.someText // Access or modify global state - "Hello Universe!"

      const context = getContext();
      context.someText // Access or modify local state (context) - "Hello World!"
    },
  },
} )

Actions

Actions are just regular JavaScript functions. Usually triggered by the data-wp-on directive (using event listeners) or other actions.

Async actions should use generators instead of async/await.

<div data-wp-context='{ "someText": "Hello World!" }'>

  <!-- Access global state -->
  <span data-wp-text="state.someText"></span>

  <!-- Access local state (context) -->
  <span data-wp-text="context.someText"></span>

</div>

const { state } = store( "myPlugin", {
  state: {
    someText: "Hello Universe!"
  },
  actions: {
    someAction: () => {
      state.someText // Access or modify global state - "Hello Universe!"

      const context = getContext();
      context.someText // Access or modify local state (context) - "Hello World!"
    },
  },
} )

Side effects

Automatically react to state changes. Usually triggered by data-wp-watch or data-wp-init directives.

Derived state

They return a computed version of the state. They can access both state and context.

const { state } = store( "myPlugin", {
  state: {
    amount: 34,
    defaultCurrency: 'EUR',
    currencyExchange: {
      USD: 1.1,
      GBP: 0.85,
    },
    get amountInUSD() {
      return state.currencyExchange[ 'USD' ] * state.amount,
    },
    get amountInGBP() {
      return state.currencyExchange[ 'GBP' ] * state.amount,
    },
  },
} );

Accessing data

The store contains all the store properties, like state, actions or callbacks. They are returned by the store() call, so you can access them by destructuring it:

const { state, actions } = store( "myPlugin", {
  // ...
} );

The store() function can be called multiple times and all the store parts will be merged:

store( "myPlugin", {
  state: {
    someValue: 1,
  }
} );

const { state } = store( "myPlugin", {
  actions: {
    someAction() {
      state.someValue // = 1
    }
  }
} );

Setting the store – client side

The store method used to set the store in JavaScript can be imported from @wordpress/interactivity.

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

store( "myPlugin", {
  actions: {
    toggle: () => {
      const context = getContext();
      context.isOpen = !context.isOpen;
    },
  },
  callbacks: {
    logIsOpen: () => {
      const { isOpen } = getContext();
      // Log the value of `isOpen` each time it changes.
      console.log( `Is open: ${ isOpen }` );
    }
  },
});

Setting the store – server side

The state can also be initialized on the server using the wp_interactivity_state() function.

wp_interactivity_state( 'favoriteMovies', array(
      "1" => array(
        "id" => "123-abc",
        "movieName" => __( "someMovieName", "textdomain" )
      ),
) );

Store client methods

The store has some handy methods to allow developers to access data.

• getContext()
• getElement()

getContext() method

Retrieves the context inherited by the element evaluating a function from the store. The returned value depends on the element and the namespace where the function calling getContext() exists.

<div data-wp-interactive="myPlugin" data-wp-context='{ "isOpen": false }'>
    <button data-wp-on--click="actions.log">Log</button>
</div>

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

store( "myPlugin", {
  actions: {
    log: () => {
      const context = getContext();
      // Logs "false"
      console.log( 'context => ', context.isOpen )
    },
  },
});

getElement() method

Retrieves a read-only representation of the element that the action is bound to or called from. It returns an object with two keys:

ref is the reference to the DOM element as an HTMLElement.

attributes contains a Proxy, which adds a getter that allows to reference other store namespaces.

console.log( 'element attributes => ', element.attributes );
// Gives us...
{
    "data-wp-on--click": 'actions.increaseCounter',
    "children": ['Log'],
    "onclick": event => { evaluate(entry, event); }
}

Server functions

• wp_interactivity_config – allows to set or get a configuration array, referenced to a store namespace.
• wp_interactivity_process_directives – returns the updated HTML after the directives have been processed.
  • The core function of the Interactivity API server-side rendering. Any HTML can be processed, whether is a block or not.
• wp_interactivity_data_wp_context – returns a stringified JSON of a context directive.

Dive deeper and keep learning

Existing examples

Gallery Slider – Ryan Welcher

To-do List – Ryan Welcher

WordPress core blocks: Image lightbox, Search show/hide, Query Loop enhanced pagination

Pew Research Center’s PRC Block Library

Feedback Form

Interactivity API showcase