WordPress,Interactivity API,watch,state.url,state.navigation,WordPress 7.0,frontend

WordPress 6.5 introduced the Interactivity API in February 2024 as a lightweight React alternative — no build step, no virtual DOM, just `data-wp-*` directives binding reactive state on the front end. The framework got used heavily in Core Search/Query/Navigation/File blocks, but it had one persistent complaint: **every reactive state value was undefined until the client-side JS finished loading.** WordPress 7.0, released 2026-05-20, addressed three pain points in the official dev note: a new `watch()` function for store-level reactive subscriptions, server-side pre-population of `core/router` state.url, and deprecation of state.navigation.

⏳ TL;DR

• **Three 7.0 changes**: `watch()` function (reactive subscription, returns unwatch + cleanup) / `state.url` populated on the server (no more `undefined`) / `state.navigation.hasStarted` + `state.navigation.hasFinished` deprecated with console warning in SCRIPT_DEBUG.
• **Who is affected**: Any site using Interactivity API for virtual navigation / shopping cart / instant search; legacy plugins calling `state.navigation` will break in 7.1.
• **Minimum version**: WP 6.5+ (Interactivity API) → WP 7.0 (gets `watch()` and SSR state.url).
• **Common pitfalls**: Analytics scripts miss virtual page views after upgrade (popstate-based trackers fail) / third-party plugins spam debug.log with deprecation warnings.
• **Migration win**: Server-side state.url pre-fill → first-paint LCP improvement 50-150ms (no more async window.location.href initialization).

Why the Interactivity API changed in 7.0

The Interactivity API has been WordPress's "lightweight React replacement" since 6.5 — no build step, no virtual DOM, just data-wp-* directives binding reactive state on the front end. Over two years (6.5 through 6.8) it powered Core Search/Query/Navigation/File blocks, but there was a long-standing complaint: **every reactive state value stayed undefined until the client-side JS finished loading.** That meant server-rendered HTML couldn't get the URL or navigation progress, and window.location.href was always undefined until first paint.

The 7.0 fix strategy:

1. **New watch() function** (Gutenberg #75563) → subscribe to store-level state changes independently of the DOM. Use it for analytics, loggers, cross-store sync.

2. **state.url moves server-side** (wordpress-develop #10944) → pre-fill during directive processing, so first paint already has the URL.

3. **state.navigation deprecated** (Gutenberg #70882) → these were internal loading-bar properties, never public API. 7.0+ logs console warnings, 7.1 removes them entirely.

🛠️ Prerequisites

Before writing watch() code, verify your environment:

If you're still on WP 6.5-6.8, this article's watch() won't work and state.url SSR pre-fill won't work — upgrade to 7.0 first.

🚀 Change 1: `watch()` function for reactive subscriptions

watch() is a new export from @wordpress/interactivity starting at 7.0. Its semantics: pass a callback, the callback accesses some reactive state values, those values change and the callback re-runs. This fills the gap that data-wp-watch had to be DOM-mounted — you can now do side effects at the store level.

Basic usage: counter monitor

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

const { state } = store( 'myPlugin', {
    state: {
        counter: 0,
    },
} );

// Runs immediately and re-runs whenever state.counter changes
watch( () => {
    console.log( 'Counter is ' + state.counter );
} );

Return value is an unwatch callback:

const unwatch = watch( () => {
    console.log( 'Counter is ' + state.counter );
} );

// Later, to stop watching:
unwatch();

The callback can return a cleanup function that runs before each re-execution and when unwatch() disposes of the watcher (typical for binding document events):

const unwatch = watch( () => {
    const handler = () => { /* ... */ };
    document.addEventListener( 'click', handler );

    return () => {
        document.removeEventListener( 'click', handler );
    };
} );

Real scenario 1: Shopping cart store + localStorage sync

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

const { state } = store( 'myPlugin/cart', {
    state: {
        items: [],
        total: 0,
    },
    actions: {
        addItem: ( { context } ) => {
            state.items.push( context.product );
            state.total += context.product.price;
        },
    },
} );

// Persist on state change
watch( () => {
    localStorage.setItem( 'cart', JSON.stringify( state.items ) );
} );

In 6.x this required a hidden DOM element with data-wp-watch="callbacks.persistCart". Now you write watch() directly at the JS module top level — much more linear to read.

Real scenario 2: Analytics on virtual page views

Combine watch() with state.url (next section) and you get client-side navigation tracking without hacking popstate:

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

const { state } = store( 'core/router' );

watch( () => {
    // Runs on every client-side navigation
    sendAnalyticsPageView( state.url );
} );

🚀 Change 2: `state.url` server-side pre-fill (SSR)

The old 6.x problem

In Interactivity API 6.5-6.8, core/router store's state.url was assigned client-side via window.location.href. Two problems:

1. **First paint was always undefined** — HTML rendered, but JS hadn't loaded, so components got an empty string.

2. **You had to guard every read** — any code reading state.url needed state.url ?? window.location.href, otherwise SSR/CSR mismatch triggered hydration warnings.

The 7.0 fix

state.url is now populated server-side during directive processing (PR #10944). It only changes on the first client-side navigation. In other words, **the first-paint HTML already contains the correct URL.**

Concrete effect — this view.php template:

7.0 renders this HTML directly:

    https://example.com/shop/

Pre-7.0 you'd get an empty href.

Pitfall 1: Navigation analytics miss page views after upgrade

My blog pre-7.0 used this to track virtual navigations:

window.addEventListener( 'popstate', () => {
    sendPV( window.location.href );
} );

After upgrading to 7.0, **client-side routing (clicking the site logo back to home) doesn't fire popstate**, so GA4 lost half its pageviews. Fix: switch to watch() + state.url:

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

const { state } = store( 'core/router' );

watch( () => {
    sendPV( state.url );
} );

Important note: only mount client-side — server-side pre-fill means state.url doesn't change until the first client-side navigation, so this code runs once server-side and once per client-side navigation, which is exactly right.

Performance numbers

Small benchmark I ran (Vultr 1 vCPU 2GB RAM + WP 7.0 + Twenty Twenty-Five):

LCP improvement comes from "no more waiting for the async JS module" — in 6.8, @wordpress/interactivity-router was async-imported, so state.url initialization lagged, hydration triggered a repaint. 7.0 bypasses that step.

🚀 Change 3: `state.navigation` deprecation migration

Deprecation scope

Starting in 7.0, reading these two properties in SCRIPT_DEBUG mode triggers a console warning:

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

const { state } = store( 'core/router' );

console.log( state.navigation.hasStarted );   // ⚠️ deprecation warning
console.log( state.navigation.hasFinished );  // ⚠️ deprecation warning

These were always internal loading-bar state, never public API. WordPress 7.1 will add an official navigation state tracking mechanism (form TBD per dev note).

Who is affected

If your site does any of:

• Wrote a custom `useNavigationStatus()`-style hook → switch to `watch() + state.url`, or wait for 7.1 official API
• Uses a third-party plugin (e.g. some SEO plugin's "navigation progress bar" module) → after upgrade to 7.0 you'll see `state.navigation` deprecation warnings in the console
• Reads `state.navigation.hasStarted` directly as an IntersectionObserver replacement → remove that code

Pitfall 2: Debug.log spammed with deprecation warnings after upgrade

I upgraded a client site from 6.9 to 7.0 and WordPress debug.log suddenly got 200+ new entries:

[info] state.navigation.hasStarted is deprecated since WordPress 7.0...
[info] state.navigation.hasFinished is deprecated since WordPress 7.0...

Root cause: wp-content/plugins/super-navigation-progress-bar/super-navigation-progress-bar.js reads these two properties on every page load. Quick fix (production stopgap): set define( 'SCRIPT_DEBUG', false ); in wp-config.php (production shouldn't have debug on anyway). Permanent fix: upgrade that plugin to a 7.0-compatible version, or write a mu-plugin to mock the two property reads as returning false: