WordPress 6.8 comes with a few new best practices and requirements in the Interactivity API An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. that are part of a longer-term continuous-improvement effort. Some of the relevant changes in 6.8 are an intermediary step: They do not include these enhancements themselves, but they prepare the project to add them in a future release by adding two new deprecation warnings.
If you have been using the Interactivity API in your project, especially if you have been writing your own stores, please read on to learn how you can prepare your changes for the latest and future behavior of the API.
How to apply the latest best practices (and avoid deprecation warnings)
To help the Interactivity API speed up WordPress, the project is working towards running most store actions asynchronously by default, as a better foundation for achieving good INP (“Interaction to Next Paint”) performance. Right now, browsers invoke all synchronous Interactivity API event handlers as part of the same task—this means they stack up. This can make the user wait for longer than 50 milliseconds (also called a “long task”) for the site to react React is a JavaScript library that makes it easy to reason about, construct, and maintain stateless and stateful user interfaces.
https://reactjs.org to some interaction, like clicking a button.
Starting with 6.8, and going forward, the Interactivity API’s push towards asynchronous handlers as the default will make those long tasks less likely. The 6.8 release only prepares for the transition. In the following WordPress release, the API will automatically yield to the main thread in between handlers, so ideally there’s nothing to stack up, and nothing to make the user wait. (Also refer to async actions and the splitTask() function.)
This performance enhancement Enhancements are simple improvements to WordPress, such as the addition of a hook, a new feature, or an improvement to an existing feature. also helps with cross-plugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party. compatibility, as handlers for the same event may come from different plugins. The new requirements outlined below are an important step to prepare the Interactivity API for that future.
Wrap certain action callbacks in withSyncEvent()
Pay attention to any store action that is attached to an event listener (like data-wp-on--click) and accesses the event object: If the action callback uses any of the event properties or methods below, you need to wrap it in a newly added utility function called withSyncEvent():
- Property:
event.currentTarget
- Method:
event.preventDefault()
- Method:
event.stopImmediatePropagation()
- Method:
event.stopPropagation()
Starting in WordPress 6.8, if any action callback uses the above event properties or methods and is not wrapped in withSyncEvent(), that action callback will trigger a deprecation warning. For now, the logic will continue to work as before. But in a future WordPress release it will break if you do not migrate. For example, event.preventDefault() will not prevent the default action since the action will be asynchronous by default. As such, please make sure to resolve any deprecation warnings you see.
This correct (✅) code example illustrates how to use withSyncEvent():
import { store, withSyncEvent } from '@wordpress/interactivity';
store( 'myPlugin', {
actions: {
// `event.preventDefault()` requires synchronous event access.
preventNavigation: withSyncEvent( ( event ) => {
event.preventDefault();
} ),
// `event.target` does not require synchronous event access.
logTarget: ( event ) => {
console.log( 'event target => ', event.target );
},
// Not using `event` at all does not require synchronous event access.
logSomething: () => {
console.log( 'something' );
},
},
} );
This bad (❌) example will, going forward, emit a deprecation warning:
import { store } from '@wordpress/interactivity';
store( 'myPlugin', {
actions: {
// Missing `withSyncEvent()` around synchronous event access.
preventNavigation: ( event ) => {
event.preventDefault();
},
},
} );
Do not use actions to determine HTML HyperText Markup Language. The semantic scripting language primarily used for outputting content in web browsers. attribute values
If you have been relying on Interactivity API store functions (like actions or callbacks) to determine HTML attribute values (e.g. via data-wp-bind--attr), please revise these attributes now. Instead, use global state, local context, or derived state. And please do not combine these function calls with directive logic like the ! operator.
Starting in WordPress 6.8, any directive using a store function in combination with the ! operator will emit a deprecation warning. The logic will continue to work as before for now, but in a future WordPress release it will break if you do not migrate. More broadly, if you are using store functions in directives that determine HTML attribute values, please migrate to using global state, local context, or derived state instead. More deprecation warnings around incorrect usage of store functions are expected soon, and eventually unmigrated code is going to break.
Please refer to the following correct (✅) code example to illustrate how to use derived state:
import { store } from '@wordpress/interactivity';
store( 'myPlugin', {
state: {
get isOpen() {
const ctx = getContext();
return !! ctx.open;
},
},
} );
<div
data-wp-interactive="myPlugin"
data-wp-bind--hidden="!state.isOpen"
>
Content.
</div>
This bad (❌) example will, going forward, emit a deprecation warning:
import { store } from '@wordpress/interactivity';
store( 'myPlugin', {
actions: {
isOpen() {
const ctx = getContext();
return !! ctx.open;
},
},
} );
<div
data-wp-interactive="myPlugin"
data-wp-bind--hidden="!actions.isOpen"
>
Content.
</div>
To provide context on why this new requirement is relevant: Using store functions for anything other than the “on”, “init”, or “watch” groups of directives has always been an anti-pattern. It is now being more formally discouraged, and will in the future be made impossible.
Support for the .length property in directives
An additional Interactivity API enhancement in WordPress 6.8 is support for the .length property on strings and numeric arrays in directives, ensuring consistency between server and client rendering.
Previously, the .length property was unavailable on the server, requiring workarounds. This update allows developers to use .length within all directives that reference global state, local context, or derived state, aligning behavior across environments.
This code example illustrates using the .length property:
<div data-wp-interactive="example">
<div data-wp-bind--hidden="!state.list.length">
<input type="range" min="1" data-wp-bind--max="state.list.length">
</div>
<div data-wp-bind--hidden="!state.string.length">
<h1 data-wp-text="state.string"></h1>
</div>
</div>
This improvement streamlines logic and improves developer experience.
Summary and further reading
Please refer to the following links for further reading:
- Gutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc.
https://wordpress.org/gutenberg/ pull request #68097 for the
withSyncEvent and new directive requirement enhancements
- Gutenberg issues #64944 and #69552 with additional context on the long-term plans to run Interactivity API actions asynchronously by default.
- Gutenberg issue #69269 with additional context on the long-term plans to more clearly separate directives that do something vs that determine a value.
- Trac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress. ticket Created for both bug reports and feature development on the bug tracker. #62582 for support of the
.length property.
- Documentation for understanding global state, local context, or derived state.
Co-authored by @gziolo.
Props to @westonruter, @jonsurrell, @webcommsat, @marybaum for review and proofreading.
#6-8, #dev-notes, #dev-notes-6-8, #interactivity-api, #performance
