@wordpress/interactivity-router

The package @wordpress/interactivity-router enables loading content from other pages without a full page reload. Currently, the only supported mode is “region-based”. Full “client-side navigation” is still in experimental phase.

The package defines an Interactivity API store with the core/router namespace, exposing state and 2 actions: navigate and prefetch to handle client-side navigation.

The @wordpress/interactivity-router package was introduced in WordPress Core in v6.5. This means this package is already bundled in Core in any version of WordPress higher than v6.5.

Usage

The package is intended to be imported dynamically in the view.js files of interactive blocks. This is done in order to reduce the JS bundle size on the initial page load.

/* view.js */

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

// This is how you would typically use the navigate() action in your block.
store( 'my-namespace/myblock', {
    actions: {
        // The withSyncEvent() utility needs to be used because preventDefault() requires synchronous event access.
        goToPage: withSyncEvent( function* ( e ) {
            e.preventDefault();

            // We import the package dynamically to reduce the initial JS bundle size.
            // Async actions are defined as generators so the import() must be called with `yield`.
            const { actions } =
                yield import( '@wordpress/interactivity-router' );
            yield actions.navigate( e.target.href );
        } ),
    },
} );

Now, you can call actions.navigate() in your block’s view.js file to navigate to a different page or e.g. pass it to a data-wp-on--click attribute.

When loaded, this package adds the following state and actions to the core/router store:

const { state, actions } = store( 'core/router', {
    state: {
        url: window.location.href,
        // `navigating` and `initiator` are also part of the store's state,
        // but they are written by `navigate()` instead of being declared
        // here, so both read `undefined` until the first navigation.
    },
    actions: {
        *navigate(href, options) {...},
        prefetch(url, options) {...},
    }
})

Beyond the current URL, the store’s state describes the navigation itself: whether one is in flight (state.navigating) and who started it (state.initiator). See State below.

Directives

data-wp-router-region

It defines a region that is updated on navigation. It requires a unique ID as the value and must be used alongside data-wp-interactive to receive the proper namespace. Router regions can be placed anywhere within interactive regions, including nested interactive elements.

The value can be a string with the region ID, or a JSON object containing the id and an optional attachTo property.

Example:

<div data-wp-interactive="myblock" data-wp-router-region="main-list">
    <ul>
        <li><a href="/post-1">Post 1</a></li>
        <li><a href="/post-2">Post 2</a></li>
        <li><a href="/post-3">Post 3</a></li>
    </ul>
    <a data-wp-on--click="actions.navigate" href="/page/2">Page 2</a>
</div>

Navigation ignores a router region inside the inert content of a data-wp-html element, whether that’s the server-rendered fallback or HTML the directive inserted, as if the region had no data-wp-router-region attribute. data-wp-html on a router region itself doesn’t make the region’s content inert, because data-wp-router-region takes precedence. See Where to place router regions in the Client-Side Navigation guide.

The attachTo property is a CSS selector that points to the parent element where the new router region should be rendered. This is useful for regions that may not exist on the initial page but are present on subsequent pages, like a modal or an overlay. The router uses the first element on the current page that matches the selector, skipping any element with inert data-wp-html content and anything inside that content.

When navigating between pages:

• If a region exists on both the current and the new page, its content is updated, and attachTo doesn’t move it. If the new page’s attachTo has no usable element, though, the region shows nothing, as if the new page didn’t have it.
• If a region without attachTo exists on the new page but not on the current one, it is not added to the DOM.
• If a region with attachTo exists on the new page but not on the current one, it is created and appended to the parent element specified in attachTo.
• If the new page’s attachTo has no usable element, the region isn’t attached, and the rest of the navigation completes as if the new page didn’t have the region: the other regions update, the title and URL change, and no error is thrown. There’s no usable element when the selector matches nothing, when every match has inert data-wp-html content or is inside it, or when the selector isn’t valid. The router resolves attachTo every time it renders the page, including on Back and Forward, so a later render can still attach the region.
• If a region exists on the current page but not on the new one, it is removed from the DOM. attachTo is ignored in this case.

The router ignores attachTo for a region that the initial page declared with attachTo: on every later page, that region behaves as a regular router region.

Example with attachTo:

<div
    data-wp-interactive="myblock"
    data-wp-router-region='{ "id": "myblock/overlay", "attachTo": "body" }'
>
    I'm in a new region!
</div>

Actions

navigate

Navigates to the specified page.

This function normalizes the passed href, fetches the page HTML if needed, and updates any interactive regions whose contents have changed in the new page. It also creates a new entry in the browser session history.

Params

navigate( href: string, options: NavigateOptions = {} )

• href: The page href.
• options: Options object.
  • force: If true, it forces re-fetching the URL. navigate() always caches the page, so if the page has been navigated to before, it will be used. Default is false.
  • html: HTML string to be used instead of fetching the requested URL.
  • replace: If true, it replaces the current entry in the browser session history. Default is false.
  • timeout: Time until the navigation is aborted, in milliseconds. Default is 10000.
  • loadingAnimation: Whether an animation should be shown while navigating. Default to true.
  • screenReaderAnnouncement: Whether a message for screen readers should be announced while navigating. Default to true.
  • initiator: Identifies who initiated this navigation, published on state.initiator for as long as it is in flight. A nonempty string is used verbatim and always wins. null suppresses attribution, so state.initiator reads null throughout. If omitted (the default), the initiator is derived from the ambient directive scope: the id of the nearest data-wp-router-region enclosing the element whose directive called the action, including that element itself, or null when there is none. Any other value (an empty string, a number, an object, false) is treated as null and, with SCRIPT_DEBUG enabled, logs a warning; it never falls back to deriving the initiator.

prefetch

Prefetches the page for the passed URL. The page is cached and can be used for navigation.

The function normalizes the URL and stores internally the fetch promise, to avoid triggering a second fetch for an ongoing request.

Params

prefetch( url: string, options: PrefetchOptions = {} )

• url: The page url.
• options: Options object.
  • force: If true, forces fetching the URL again.
  • html: HTML string to be used instead of fetching the requested URL.

State

All three properties are reactive, so reading them inside a directive or a watch() callback subscribes to their changes.

• state.url (string): Synchronized with the current URL.
• state.navigating (boolean | undefined): Truthy while a client-side navigation is in flight. The start is published as soon as the navigation enters the client-side pipeline, without waiting for the destination page; the end is published after the new content has been committed to the DOM, on a later frame, and the delay between the commit and the end is unbounded. A navigation that falls back to a full page load mid-flight keeps it truthy while the browser replaces the document, and resets it to false if the document is still there 10 seconds later; a navigation that throws while rendering ends normally, with the page possibly only partially updated. In both cases the end promises no new content. Neither the loadingAnimation nor the screenReaderAnnouncement option affects it: they change the built-in feedback, not this key.
• state.initiator (string | null | undefined): Identifies who started the navigation that is in flight — the value resolved from navigate()‘s initiator option, or null when the navigation has no identifiable initiator, as is the case for back/forward traversals, for calls made with no directive scope, and for calls made from inside a watch() that reacts to state.navigating, state.initiator or state.url (such a call does not inherit the initiator of the navigation it reacts to). The end of a navigation does not clear it: it keeps that navigation’s value until the next navigation starts, or until a back/forward traversal that reloads the document clears it to null.

Neither navigating nor initiator is declared when the store is registered, so both read undefined until the first client-side navigation writes them, and on pages where the router module never loads. Consume them by truthiness — if ( state.navigating ) and state.initiator === myRegionId — rather than comparing against false or null. Note that a binding such as data-wp-bind--aria-busy="state.navigating" renders no attribute at all while the value is undefined, rather than aria-busy="false".

A derived state.initiator carries the region’s id, not the raw data-wp-router-region attribute text. For the JSON object form it is the value of the id property, a namespace:: prefix is stripped, and an empty or non-string id reads null rather than an empty string. Compare against the id you gave the region, spelled exactly as you gave it.

For the full semantics — which navigations are covered and which produce no transition at all, what overlapping navigations do to both readings, and which directive to read them from — see Reacting to the navigation lifecycle in the Client-Side Navigation guide.

Installation

Install the module:

npm install @wordpress/interactivity-router --save

This step is only required if you use the Interactivity API outside WordPress.

Within WordPress, the package is already bundled in Core. To ensure it’s enqueued, add @wordpress/interactivity-router to the dependency array of the script module. This process is often done automatically with tools like wp-scripts.

Furthermore, this package assumes your code will run in an ES2015+ environment. If you’re using an environment with limited or no support for such language features and APIs, you should include the polyfill shipped in @wordpress/babel-preset-default in your code.

License

Interactivity API proposal, as part of Gutenberg and the WordPress project is free software, and is released under the terms of the GNU General Public License version 2 or (at your option) any later version. See LICENSE.md for complete license.