Plugins Plugin hub Backup SEO Caching Security Forms WooCommerce Images Best backup plugins
Hosting Hosting directory Shared Managed Cloud India
Themes & builders Compare Rank Math vs Yoast
Tools All tools Hosting finder Plugin stack builder Cost calculator Salt generator Theme detector Who is hosting this? Speed test Headline analyzer robots.txt generator Redirect generator Uptime calculator Blog name generator
Best lists Best backup plugins Deals
Guides All guides Speed up WordPress Choose hosting Back up WordPress
How we test

Explainers · Explainer

What Is the Interactivity API? A Plain Explanation

Short answer

The Interactivity API is WordPress's standard way to add front-end interactions to blocks, such as instant search, lightboxes, and menus that open and close. It arrived in WordPress 6.5, released on April 2, 2024. Developers describe the interaction in the HTML with directives, and keep the data and logic in a store that updates the page when the data changes.

Key takeaways

  • The Interactivity API is WordPress's standard for front-end block interactions, and it arrived in WordPress 6.5 on April 2, 2024.
  • Directives are data-wp-* attributes in the HTML that say what should happen when data changes or a visitor clicks.
  • The store holds shared state, local context, actions, and derived values for interactive blocks.
  • Core blocks such as Search, Query, Navigation, and File already use the Interactivity API.
  • Its router can swap only part of a page during navigation, without a full page reload.

What is the Interactivity API?

The Interactivity API is WordPress's standard way to add front-end interactions to blocks.

It gives block developers one shared method for things visitors do on a page, such as opening a menu, filtering a list, or expanding an image.

Before it existed, each plugin author picked a different JavaScript framework or wrote custom scripts. The Interactivity API Reference says the API provides a standard way to add interactions to the front end of blocks.

The idea is simple: the server still renders the full HTML page, and small pieces of that HTML react when data changes. A click can change a value, and the page updates only the parts that depend on that value. You do not need a separate JavaScript app to get that result.

When did WordPress add the Interactivity API?

WordPress added the Interactivity API in WordPress 6.5, released on April 2, 2024.

WordPress.org's Version 6.5 page records that WordPress 6.5 “Regina” was released to the public on April 2, 2024. The same page describes the Interactivity API as a standard method for building interactive front-end experiences with blocks.

The work started earlier. The merge announcement says the project began as an experimental plugin in early 2022, the first API version appeared in Gutenberg 16.2, and it was refined until Gutenberg 17.7. Sites on WordPress below 6.5 need Gutenberg 17.5 or higher to use it, as of November 2026.

How does the Interactivity API work?

It works in three parts: server-rendered HTML, directives in that HTML, and a JavaScript store that holds the data.

First, WordPress renders the block's HTML on the server, so visitors and search engines get a complete page. Next, directives in the HTML declare how each element should react.

Then the store holds the state and the actions that change it. When an action changes the state, the API updates the parts of the page that depend on it.

The Directives and Store guide explains that DOM elements connect to data in the state and context through directives. If that data changes, the directives react and update the DOM. You describe what should happen, and the API handles the updates.

What are directives in the Interactivity API?

Directives are special HTML attributes, starting with data-wp-, that tell the API how an element should behave.

They sit in the block's markup, in render.php for dynamic blocks or save.js for static blocks. The API reads them on the server and in the browser, so the first render and later updates stay in step. Here are the main ones.

DirectiveWhat it does
data-wp-interactiveTurns on interactivity for an element and its children, and names the store
data-wp-contextHolds local data for one element and its children, written as JSON
data-wp-on--clickRuns an action when a visitor clicks the element
data-wp-bind--hiddenShows or hides an element based on a value
data-wp-textSets the text inside an element from state or context
data-wp-class--is-openAdds or removes a class based on a true or false value
data-wp-style--colorSets an inline style based on a value
data-wp-router-regionMarks a section the router can swap during navigation

The data-wp-interactive directive is required for the engine to work. The Directives and Store guide states that using it is a requirement for the Interactivity API engine. A typical region sets the data-wp-interactive attribute to the store name, such as myPlugin.

What is the store in the Interactivity API?

The store is the JavaScript object that holds the data and logic for an interactive block.

It contains state, actions, and callbacks. State is the data the page shows.

Actions are functions that run when a visitor does something, such as clicking a button, and they change the state or context. The store is created with the store() function from the @wordpress/interactivity package, which WordPress has bundled in core since version 6.5.

State can start on the server. The PHP function wp_interactivity_state() sets the first state in a block's render.php file, and that server state merges with the stores defined in the block's view.js file. The render.php template style itself arrived in WordPress 6.1.

A block also has to declare that it uses the API. It adds "interactivity": true to the supports field in its block.json file, and its JavaScript runs as a Script Module through viewScriptModule. Script Modules have been available since WordPress 6.5.

What is the difference between state, context, and config?

State is shared data, context is local data for one element, and config is fixed data that never triggers an update.

Global state can be read and changed by any interactive block on the page that uses the same store. That shared access lets two separate blocks stay in step, so an “add to cart” block can update a separate cart block.

Local context belongs to one element and its children only, which keeps each copy of a block independent, such as two menus on one page.

Derived state is a value the store works out from state or context when it is needed, instead of storing a second copy that could drift out of date.

Config is different again: it holds fixed values sent from the server, such as API endpoints, nonces, or feature flags, and changing it does not update the page.

The API is reactive, so a change to state or context updates the UI parts that depend on it. It also does not force you to replace whole data objects when you change one value, which keeps the code short.

Which WordPress blocks already use the Interactivity API?

Core blocks that use it include Search, Query, Navigation, and File.

The Interactivity API Reference names Search, Query, Navigation, and File as core blocks that use the API. The Image block's lightbox, which expands an image when you click it, also runs on it.

That use started before the public launch. The merge announcement says that in WordPress 6.4, the Image, Search, File, Navigation, and Query blocks were rebuilt with the private version of the API. That work fixed access issues and added the long-awaited lightbox feature for images.

Because core blocks already use it, the code is already on many sites. The merge announcement also notes that interactivity scripts load on the front end only when at least one interactive block is present, so pages without one do not get the extra JavaScript.

What is client-side navigation in the Interactivity API?

Client-side navigation swaps part of a page for new content without a full page reload.

It comes from the @wordpress/interactivity-router package, which WordPress has bundled in core since version 6.5. The router store uses the core/router namespace and exposes 2 actions, navigate and prefetch, according to the router package page.

The key idea is the router region. You mark a section with data-wp-router-region and a unique ID, and the router replaces only matching regions when a visitor moves to a new page.

The Client-Side Navigation guide explains that the rest of the page stays untouched, state is kept across the move, and the server still renders full HTML pages, so search engines can crawl the site normally.

Region-based navigation is the recommended mode. Full-page client-side navigation, which treats the whole page body as one region, is still experimental as of November 2026. The Query block supports region-based navigation on its own when its “Force page reload” toggle is off.

How can you check if a site uses the Interactivity API?

Check the WordPress version first, then look for data-wp-interactive in the page source.

  1. Open the WordPress admin and go to Dashboard, then Updates, to confirm the site runs WordPress 6.5 or later.
  2. Visit a page with a Search block, a Query block, or an Image block with a lightbox.
  3. Right-click the page in your browser and choose View Page Source.
  4. Search the source for data-wp-interactive to find interactive regions.
  5. Click the lightbox or use instant search to see the interaction run without a reload.

If the version is below 6.5, the API is absent unless the Gutenberg plugin at version 17.5 or higher is active. If you see no data-wp-interactive attributes, the page has no interactive blocks, and the scripts may not load at all. That is normal, since WordPress loads them only when an interactive block is present.

What is the Interactivity API not?

It is not a page builder, a theme, or a full JavaScript framework you install.

It does not build pages for you or replace the block editor. It adds behaviour to blocks that already exist, which is why it pairs with the block editor rather than replacing it. If you are weighing editors, our guide to the block editor vs page builders explains where each tool fits.

It is also not a headless setup. Pages still render on the server in WordPress, and the API adds interaction on top of that HTML.

A headless WordPress site, by contrast, hands the whole front end to a separate app. The Interactivity API keeps the WordPress front end in place.

It is not a replacement for all JavaScript on a site either. Existing scripts keep working, and the API is meant to be the shared standard for block interactions.

If you are deciding where a feature should live, our guide on whether a feature belongs in a theme or a plugin can help you place it.

What mistakes should you avoid?

Do not treat the API as a shortcut for every interaction, and do not skip the server-rendered first view.

  • Do not put shared data in local context, or two blocks that should stay in step will drift apart.
  • Do not put per-item data in global state, or every copy of a block will change at once.
  • Do not forget data-wp-interactive on the outer element, since the engine will not run without it.
  • Do not render raw HTML with data-wp-text, since plain strings never render as HTML by design; data-wp-html needs a value built with asDangerousHTML().
  • Do not add the scripts by hand on every page; WordPress loads them only when an interactive block is present, and forcing them everywhere adds weight for no gain. If speed is a worry, our guide on how to speed up WordPress covers the checks that matter most.

The proposal behind the API is tracked in Trac ticket 60356, which links the merge work and its history.

Frequently asked questions

Do you need to install anything to use the Interactivity API?

No, not on WordPress 6.5 or later, because the @wordpress/interactivity package is bundled in core. On older WordPress versions you need Gutenberg 17.5 or higher active. Developers still need a block development setup to build a custom interactive block, but site owners do not install anything extra to use core blocks that already rely on it.

Can you use the Interactivity API in a classic theme?

Yes. Classic themes can add directives directly in their PHP template files and process them with wp_interactivity_process_directives(). You also register your script module by hand instead of relying on a block.json file. Blocks are the simpler path, since block.json handles the setup, but classic themes are supported.

Is the Interactivity API the same as the Block Bindings API?

No, they are separate APIs that arrived in the same release. The Block Bindings API links core block attributes to custom fields and other dynamic content during rendering. The Interactivity API handles what happens in the browser after the page loads, such as clicks, state changes, and navigation without a full reload.

Does the Interactivity API replace jQuery on a WordPress site?

No. It is a standard for front-end block interactions, not a replacement for every script on a site. Existing JavaScript and jQuery code keeps working. The point is that new interactive blocks share one method instead of each plugin shipping its own framework, which keeps the total JavaScript lower over time.

Will the Interactivity API break caching on a site?

No, it should not. Pages still render as full HTML on the server, so a cache can store and serve them as usual. The JavaScript only adds behaviour in the browser after the page loads. Client-side navigation also fetches full HTML pages from the server and swaps only the marked regions, so cached pages still work.

Sources

  1. Interactivity API Reference WordPress Developer Resources
  2. Directives and Store WordPress Developer Resources
  3. Merge Announcement: Interactivity API Make WordPress Core
  4. Version 6.5 WordPress.org
  5. Client-Side Navigation WordPress Developer Resources
  6. @wordpress/interactivity-router WordPress Developer Resources
  7. Trac ticket 60356: Interactivity API WordPress Core Trac

Is your product missing, or something out of date?

Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.

About the editors

WPLegible editors

Researched from the primary sources listed above and checked against our editorial rules. About the site · How we test