Changelog - Tracking Breaking Changes in the Interactivity API

[luisherranz]

The Interactivity API is an ongoing initiative that aims to standardize the creation of interactive blocks. You can read the detailed proposal here. It's important to note that this API is currently in an experimental phase, which implies that we are in the process of rapid iteration and occasional introduction of breaking changes.

Testing & Feedback

We would be thrilled if you decide to test out this innovative API. We highly value all forms of feedback on the API as it directly contributes to our progress. However, due to the possibility of breaking changes, it is crucial to stay informed before updating Gutenberg.

Subscribe to this discussion

In order to facilitate this, we will update this discussion on every new version release of Gutenberg. This will primarily focus on detailing the changes in the Interactivity API, especially the breaking ones, and providing necessary guidance for migrating your code to the new versions.

If you are testing the Interactivity API, we strongly recommend subscribing to this discussion. Remember, do not update Gutenberg until you have confirmed whether there are any breaking changes in the latest release. If such changes exist, make sure to adjust your code according to the migration guidance provided below prior to updating Gutenberg.

---

Template for updates

Gutenberg: X.X.X (Release Date)

@wordpress/interactivity version: X.X.X (changelog)

Breaking Changes

• Change 1: From previous behavior -> To new behavior (Migration steps)
• Change 2: From previous behavior -> To new behavior (Migration steps)

Non-Breaking Changes

• New feature or bug-fix 1
• New feature or bug-fix 2

[luisherranz]

Gutenberg: 16.2.1 (Jul 13, 2023)

@wordpress/interactivity version: 1.1.0 (changelog)

Initial version.

[luisherranz]

Gutenberg: 16.3.0 (Jul 26, 2023)

@wordpress/interactivity version: 1.2.0 (changelog)

Non-Breaking Changes

• Runtime support for the data-wp-style directive. (#52645)

---

It's safe to upgrade to the 16.3.0 version.

[luisherranz]

Gutenberg: 16.4 (Aug 9, 2023)

@wordpress/interactivity version: 2.0.0 (changelog)

Breaking Changes

• Remove the wp-show directive until we figure out its final implementation. (#53240)

---

Migration instructions

You can replace wp-show with data-wp-bind--hidden.

Before:

<div data-wp-show="context.isOpen">
  This is only shown when `context.isOpen` is `true`.
</div>

After:

<div data-wp-bind--hidden="!context.isOpen">
  This is only shown when `context.isOpen` is `true`.
</div>

Notice that the value of hidden is reserved and it's hidden on false and unhidden on true. For that reason, using ! is required to reverse the boolean (!context.isOpen).

The hidden attribute doesn't work if the element has a display CSS property. In that case, you can use data-wp-style--display to set an inline display that overrides the other one.

The value of display is not true and false, but none and inherit. So you might need to create a selector as well:

Before:

<div data-wp-show="context.isOpen">
  This is only shown when `context.isOpen` is `true`.
</div>

After:

<div data-wp-style--display="selector.isOpen">
  This is only shown when `context.isOpen` is `true`.
</div>

store({
  selectors: {
    isOpen: ({ context }) => (context.isOpen ? "inherit" : "none"),
  },
});

We'll add wp-show back once the implementation is stable. The discussion is happening here.

[luisherranz]

Gutenberg: 16.5.0 (Aug 23, 2023)

@wordpress/interactivity version: 2.1.0 (changelog)

Non-Breaking Changes

• Allow passing optional afterLoad callbacks to store calls. (#53363)

---

It's safe to upgrade to the 16.5.0 version.

[luisherranz]

Gutenberg: 16.6.0 (Sep 6, 2023)

@wordpress/interactivity version: 2.2.0 (changelog)

Non-Breaking Changes

• Support region-based client-side navigation. (#53733)
• Support keys using data-wp-key. (#53844)
• Merge new server-side rendered context on client-side navigation. (#53853)
• Improve data-wp-bind hydration to match Preact's logic. (#54003)
• Add new directives that implement the Slot and Fill pattern: data-wp-slot-provider, data-wp-slot and data-wp-fill. (#53958)

⚠️ The slot/fill directives are very experimental and most likely subject to change. Please, use with care!

---

It's safe to upgrade to the 16.6.0 version.

[luisherranz]

Gutenberg: 16.7.0 (Sep 27, 2023)

@wordpress/interactivity version: 2.3.0 (changelog)

Non-Breaking Changes

• Improve navigate() to render only the result of the last call when multiple happen simultaneously. (#54201)
• Remove role attribute when set to null in data-wp-bind. (#54608)
• Add timeout option to navigate(), with a default value of 10000 milliseconds. (#54474)

---

It's safe to upgrade to the 16.7.0 version.

[luisherranz]

Gutenberg: 16.8.0 (Oct 11, 2023)

@wordpress/interactivity version: 2.4.0 (changelog)

---

No updates. It's safe to upgrade to the 16.8.0 version.

[luisherranz]

Gutenberg: 16.9.0 (Oct 25, 2023)

@wordpress/interactivity version: 2.5.0 (changelog)

---

No updates. It's safe to upgrade to the 16.9.0 version.

[luisherranz]

Gutenberg: 17.0.0 (Nov 9, 2023)

@wordpress/interactivity version: 2.6.0 (changelog)

Non-Breaking Changes

• Update the title when using enhanced pagination. (#55446)

---

It's safe to upgrade to the 17.0.0 version.

[luisherranz]

Gutenberg: 17.1.0 (Nov 22, 2023)

@wordpress/interactivity version: 2.7.0 (changelog)

---

No updates. It's safe to upgrade to the 17.1.0 version.

[luisherranz]

Gutenberg: 17.2 (Dec 6, 2023)

@wordpress/interactivity version: 3.0.0 (changelog)

Breaking Changes

• New store() API:
  • Proposal.
  • PR.
• Rename data-wp-effect to data-wp-watch:
  • Proposal
  • PR
• Modules and Import Maps:
  • Proposal
  • Tracking Issue
  • PR

---

Migration instructions

1. New store() API

1. Namespaces are now defined in the data-wp-interactive directive

   Instructions: Move your namespace to the data-wp-interactive directive, and remove it from the rest of the directives and their references.

   Before:

   <div data-wp-interactive>
     <div data-wp-context='{ "myPlugin": { "isOpen": false } }'>
       <span data-wp-bind--hidden="context.myPlugin.isOpen">Hi there 👋</span>
     </div>
   </div>

   After:

   <div data-wp-interactive='{ "namespace": "myPlugin" }'>
     <div data-wp-context='{ "isOpen": false }'>
       <span data-wp-bind--hidden="context.isOpen">Hi there 👋</span>
     </div>
   </div>

2. Namespaces are now defined once for the whole store

   Instructions: Move your namespace to the first parameter of the store() call and remove it from the properties.

   Before:

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

   After:

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

3. Callbacks don't get the store as a parameter anymore

   The store() call now returns the store object for that namespace.

   Instructions: To access the properties of the store, destructure one of the calls to store().

   Before:

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

   After:

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

4. Callbacks don't get the context as a parameter anymore

   Instructions: To access the context, use the new getContext() function.

   Before:

   store({
     actions: {
       myPlugin: {
         someAction({ context }) {
           context.myPlugin.someValue; // "..."
         },
       },
     },
   });

   After:

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

5. Callbacks don't get the DOM element as a parameter anymore

   Instructions: To access the DOM element, use the new getElement() function, which returns it in a property called ref.

   Before:

   store({
     actions: {
       myPlugin: {
         someAction({ ref }) {
           ref.focus();
         },
       },
     },
   });

   After:

   store("myPlugin", {
     actions: {
       someAction() {
         const { ref } = getElement();
         ref.focus();
       },
     },
   });

6. Derived state now is created using getters

   Instructions: Move the selectors to state and use getters instead of regular functions.

   Before:

   store({
     state: {
       myPlugin: {
         counter: 1,
       },
     },
     selectors: {
       myPlugin: {
         double({ state }) {
           return state.counter * 2;
         },
       },
     },
   });

   After:

   const { state } = store("myPlugin", {
     state: {
       counter: 1,
       get double() {
         return state.counter * 2;
       },
     },
   });

   Getters can also use getContext or getElement.

   Before:

   store({
     selectors: {
       myPlugin: {
         someText({ context }) {
           return context.isOpen ? "close" : "open";
         },
       },
     },
   });

   After:

   const { state } = store("myPlugin", {
     state: {
       get someText() {
         const { isOpen } = getContext();
         return isOpen ? "close" : "open";
       },
     },
   });

   When getters are used in other callbacks, there is no need to pass the store anymore.

   Before:

   store({
     state: {
       myPlugin: {
         counter: 1,
       },
     },
     selectors: {
       myPlugin: {
         double({ state }) {
           return state.counter * 2;
         },
       },
     },
     actions: {
       myPlugin: {
         someAction(store) {
           const { selectors } = store;
           console.log(selectors.myPlugin.double(store));
         },
       },
     },
   });

   After:

   const { state } = store("myPlugin", {
     state: {
       counter: 1,
       get double() {
         return state.counter * 2;
       },
     },
     actions: {
       someAction() {
         console.log(state.double);
       },
     },
   });

7. Remove state from wp_store (temporary change)

   We are still working on the migration from wp_store to wp_initial_state. Once that work is finished, the new API will be like this.

   Before:

   wp_store( array(
     'state' => array(
       'myPlugin' => array(
         'someValue'  => 'some value',
         'someNumber' => 123,
       ),
     ),
     'selectors' => array(
       'myPlugin' => array(
         'someDerivedValue' => 'some derived value',
       ),
     ),
   ) );

   After:

   wp_initial_state( 'myPlugin', array(
     'someValue'        => 'some value',
     'someNumber'       => 123,
     'someDerivedValue' => 'some derived value',
   ) );

   Instructions: We will try to ship the new wp_initial_state function in GB 17.3, but in the meantime, you can keep using wp_store without the state property.

   Before:

   wp_store( array(
     'state' => array(
       'myPlugin' => array(
         'someValue'  => 'some value',
         'someNumber' => 123,
       ),
     ),
     'selectors' => array(
       'myPlugin' => array(
         'someDerivedValue' => 'some derived value',
       ),
     ),
   ) );

   After:

   wp_store( array(
     'myPlugin' => array(
       'someValue'  => 'some value',
       'someNumber' => 123,
       'someDerivedValue' => 'some derived value',
     ),
   ) );

8. Accessing other namespaces

   Instructions: To reference other namespaces in the directives, you can use the new :: syntax.

   <div data-wp-interactive='{ "namespace": "myPlugin" }'>
     <span data-wp-bind--hidden="state.isOpen">
       I'm using the default namespace ("myPlugin")
     </span>
     <span data-wp-bind--hidden="otherPlugin::state.isOpen">
       I'm using the "otherPlugin" namespace
     </span>
   </div>

   Instructions: To access the state or actions of other namespaces, you can now use the store() function.

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

   Instructions: To access the context of other namespaces, you can pass the namespace to the getContext() function.

   store("myPlugin", {
     actions: {
       someAction: () => {
         const myContext = getContext();
         const otherContext = getContext("otherPlugin");
       },
     },
   });

9. Async actions are created using generators

   Because of the way we internally hook scoped functions like getContext() to action or derived state executions, we need to take control of asynchronous actions. That is not possible using async/await, but fortunately, it's possible when using generators. There's a longer explanation for the reasons behind this change in the new store() API proposal.

   Instructions: Replace async with * and await with yield.

   Before:

   store({
     actions: {
       myPlugin: {
         async someAction() {
           await fetch("...");
         },
       },
     },
   });

   After:

   store("myPlugin", {
     actions: {
       *someAction() {
         yield fetch("...");
       },
     },
   });

   Even though this syntax change is necessary, you can keep thinking about these actions as async functions because they are automatically converted.

   const { actions } = store("myPlugin", {
     actions: {
       *someAction() {
         yield fetch("...");
       },
       *otherAction() {
         yield actions.someAction();
       },
     },
   });
   
   const externalFunction = async () => {
     // You can use them in external functions as well.
     await actions.someAction();
   };

2. Rename data-wp-effect to data-wp-watch

Instructions: Replace data-wp-effect with data-wp-watch.

The internals haven't changed, so the referenced callbacks will keep working exactly as before.

Before:

<div data-wp-effect="effects.someSideEffect"></div>

After:

<div data-wp-watch="effects.someSideEffect"></div>

In our Core blocks and documentation, we have also changed the naming convention of the effects property and replaced it with the callbacks property to better accommodate the usage of these types of side effects outside of the data-wp-effects directive, but that's not enforced or mandatory:

store("myPlugin", {
  callbacks: {
    someSideEffect() {
      // Some logic...
    },
  },
});

<div data-wp-watch="callbacks.someSideEffect"></div>

3. Modules and Import Maps

Starting from Gutenberg 17.2, the @wordpress/interactivity package will only be exposed as an ES module.

This means that the window.wp.interactivity global is gone and if you want to access the APIs, you have to use a module that can access @wordpress/interactivity using the import map.

Before:

<script src="/wp-content/plugins/gutenberg/.../interactivity.js" defer></script>
<script src="/wp-content/plugins/my-plugin/.../view.js" defer></script>

// import { store } from '@wordpress/interactivity';
// Converted to this syntax by the DependencyExtractionWebpack plugin.
const { store } = window.wp.interactivity;

After:

<script type="importmap">
  { "imports": {
      "@wordpress/interactivity": "/wp-content/plugins/gutenberg/.../interactivity.js"
  } }
</script>
<script type="module" src="/wp-content/plugins/my-plugin/.../view.js"></script>

import { store } from "@wordpress/interactivity";

There is no support for modules in neither wp-script or block.json yet, but we will work on it. In the meantime, our recommendation is:

1. Remove your view.js from the viewScript field of the block.json.

2. Use the new gutenberg_register_module function right after your register_block_type call, and register the original file (not the one in the build folder) with the @wordpress/interactivity dependency:

   function my_plugin_register_block() {
     register_block_type( __DIR__ . '/build' );
   
     gutenberg_register_module(
       'my-plugin-block-view',
       plugin_dir_url( __FILE__ ) . 'src/view.js',
       array( '@wordpress/interactivity' ),
       '0.1.0'
     );
   }
   add_action( 'init', 'my_plugin_register_block' );

3. Use the new gutenberg_enqueue_module function in your render_callback or render.php:

   <?php
   gutenberg_enqueue_module( 'my-plugin-block-view' );
   ?>
   
   <div ...>
     ...
   </div>

If you have multiple files and you need to bundle them into a single one, our recommendation is to use esbuild with the bundle: true option.

---

If you have questions or if something is not working as expected, feel free to open a new discussion in the Interactivity API category.

[luisherranz]

Gutenberg: 17.3.0 (Dec 20, 2023)

@wordpress/interactivity version: 3.1.0 (changelog)

---

We haven't finished working on wp_initial_state so there are now new updates yet. It's safe to upgrade to the 17.3.0 version.

[luisherranz]

Gutenberg: 17.4.0 (Jan 3, 2024)

@wordpress/interactivity version: 3.1.0 (changelog)

---

We still haven't finished wp_initial_state, so no new updates yet. It's safe to upgrade to the 17.4.0 version.

[luisherranz]

Gutenberg: 17.5 (Jan 17, 2023)

@wordpress/interactivity version: 3.2.0 (changelog)

Breaking Changes

• Implement wp_initial_state(). (57556)

Enhancements

• Interactive template: Use viewModule. (57712)

---

Migration instructions

1. wp_initial_state

wp_store has been removed and replaced with wp_initial_state.

Previously:

wp_store( array(
  'state' => array(
    'myPlugin' => array(
      'isOpen' => false
    )
  )
));

Now:

wp_initial_state( 'myPlugin', array(
  'isOpen' => false
));

Important: we will likely rename it again to wp_interactivity_state in the near future. You can follow this PR if you are interested.

2. viewModule

You can now start using the new viewModule property in your block.json instead of manually registering and enqueuing the module with gunteberg_register_module and gutenberg_enqueue_module:

{
  "viewModule": "file:./view.js"
}

The only change required is to add --experimental-modules to the wp-scripts commands. Your package.json should be:

{
  "scripts": {
    "build": "wp-scripts build --experimental-modules",
    "start": "wp-scripts start --experimental-modules"
  }
}

[DAreRodz]

Gutenberg: 18.2 (Apr 24, 2024)

@wordpress/interactivity version: 5.5.0 (changelog)
@wordpress/interactivity-router version: 1.6.0 (changelog)

Non-breaking changes

• Include preact/debug when SCRIPT_DEBUG is enabled. (#60514)
• Return useMemo and useCallback hooks. (#60474)
• Allow multiple event handlers for the same type with data-wp-on. (#60661)
• Update the query block to permit non-core interactive blocks. (#60006)
• Interactivity API refactor to TypeScript (utils & kebabToCamelCase). (#60149)

---

It's safe to upgrade to the 18.2 version.

[DAreRodz]

Gutenberg: 18.3 (May 8, 2024)

@wordpress/interactivity version: 5.6.0 (changelog)
@wordpress/interactivity-router version: 1.7.0 (changelog)

Non-breaking changes

• Add full-page client-side navigation experiment setting. (#59707)

---

It's safe to upgrade to the 18.3 version.

[DAreRodz]

Gutenberg: 18.4 (May 23, 2024)

@wordpress/interactivity version: 5.7.0 (changelog)
@wordpress/interactivity-router version: 1.8.0 (changelog)

Non-breaking changes

• Allow multiple event handlers for the same type with data-wp-on-document and data-wp-on-window. (#61009)
• Prevent empty namespace or different namespaces from killing the runtime. (#61409)
• Prevent wrong written directives from killing the runtime. (#61249)

---

It's safe to upgrade to the 18.4 version.

[DAreRodz]

Gutenberg: 18.5 (Jun 5, 2024)

@wordpress/interactivity version: 6.0.0 (changelog)
@wordpress/interactivity-router version: 2.0.0 (changelog)

Non-breaking changes

• Introduce wp-on-async directive as performant alternative over synchronous wp-on directive. (#61885)
• Increase directive wp-each-child priority. (#62293)
• Fix null and number strings as namespaces runtime error. (#61960)
• Turn named capturing groups back into numbered ones inside toVdom. (#62293)
• Clarify some warning messages. (#61730)
• Move all utils inside utils.ts. (#61721)
• Move init.js to TypeScript. (#61723)
• Refactor interactivity-router to TS. (#61730)

---

It's safe to upgrade to the 18.5 version.

[DAreRodz]

Gutenberg: 18.6 (Jun 20, 2024)

@wordpress/interactivity version: 6.1.0 (changelog)
@wordpress/interactivity-router version: 2.1.0 (changelog)

---

No updates. It's safe to upgrade to the 18.6 version.

[DAreRodz]

Gutenberg: 18.7 (Jul 3, 2024)

@wordpress/interactivity version: 6.2.0 (changelog)
@wordpress/interactivity-router version: 2.2.0 (changelog)

Non-breaking changes

• Export splitTask function from @wordpress/interactivity package to facilitate yielding to the main thread. (#62665)

---

It's safe to upgrade to the 18.7 version.

[DAreRodz]

Gutenberg: 18.8 (Jul 17, 2024)

@wordpress/interactivity version: 6.3.0 (changelog)
@wordpress/interactivity-router version: 2.3.0 (changelog)

---

No updates. It's safe to upgrade to the 18.8 version.

[DAreRodz]

Gutenberg: 18.9 (Jul 31, 2024)

@wordpress/interactivity version: 6.4.0 (changelog)
@wordpress/interactivity-router version: 2.4.0 (changelog)

---

No updates. It's safe to upgrade to the 18.9 version.

[DAreRodz]

Gutenberg: 19.0 (Aug 14, 2024)

@wordpress/interactivity version: 6.5.0 (changelog)
@wordpress/interactivity-router version: 2.5.0 (changelog)

Enhancements

• Refactor internal proxy and signals system (#62734).

Bug fixes

• Prevent overriding of existing properties on state and context after a client-side navigation (#62734).
• Context inheritance is now ensured to be shallow (#62734).

---

It should be safe to upgrade to the 19.0 version, although take a look at your context inheritance in case you are relying on deep inheritance of context properties, and at your existing state/context properties if you are working with client-side navigation.

[DAreRodz]

Gutenberg: 19.1 (Aug 28, 2024)

@wordpress/interactivity version: 6.6.0 (changelog)
@wordpress/interactivity-router version: 2.6.0 (changelog)

Bug fixes

• Fix context inheritance from namespaces different than the current one (#64677).

---

It's safe to upgrade to the 19.1 version.

[DAreRodz]

Gutenberg: 19.2 (Sep 12, 2024)

@wordpress/interactivity version: 6.7.0 (changelog)
@wordpress/interactivity-router version: 2.7.0 (changelog)

Enhancements

• Improve internal deepMerge function (#64879).

Bug Fixes

• Fix computeds without scope in Firefox (#64825).

---

It's safe to upgrade to the 19.2 version

[DAreRodz]

Gutenberg: 19.3 (Sep 25, 2024)

@wordpress/interactivity version: 6.8.0 (changelog)
@wordpress/interactivity-router version: 2.8.0 (changelog)

Enhancements

• Improve TypeScript support for generators (#64577).
• Refactor internal context proxies implementation (#64713).

Bug Fixes

• Prevent calling proxifyContext over an already-proxified context inside wp-context (#65090).
• Update iterable signals when deepMerge() adds new properties (#65135).

---

It's safe to upgrade to the 19.3 version.

[DAreRodz]

Gutenberg: 19.4 (Oct 9, 2024)

@wordpress/interactivity version: 6.9.0 (changelog)
@wordpress/interactivity-router version: 2.9.0 (changelog)

---

No changes. It's safe to upgrade to the 19.4 version.

[DAreRodz]

Gutenberg: 19.5 (Oct 23, 2024)

@wordpress/interactivity version: 6.10.0 (changelog)
@wordpress/interactivity-router version: 2.10.0 (changelog)

Enhancements

• Improvements to the experimental full-page navigation (#64067):
  • Remove the src attributes from prefetched script tags.
  • Use .textContent instead of .innerText to set <script> contents.
  • Use populateServerData() with state from the server.
  • Wait for the load event of the script element before evaluating it.
  • Make renderRegions() an async function.
  • Only prefetch module scripts, never prefetch regular scripts. That's because regular scripts (without async or defer attributes) found in the head are blocking and must be executed in order. When prefetching there is no guarantee that the scripts will execute in the order they are prefetched. Module scripts can be executed in any order.

Bug Fixes

• Fix an issue where "default" could not be used as a directive suffix (#65815).
• Correctly handle lazily added, deeply nested properties with deepMerge() (#65465).

---

It's safe to upgrade to the 19.5 version.

[DAreRodz]

Gutenberg: 19.6 (Nov 6, 2024)

@wordpress/interactivity version: 6.11.0 (changelog)
@wordpress/interactivity-router version: 2.11.0 (changelog)

Bug Fixes

• Fix reactivity of undefined objects and arrays added with deepMerge() (#66183).

---

It's safe to upgrade to the 19.6 version.