iAPI Docs: Add client-side navigation guide under "Core Concepts" by DAreRodz · Pull Request #75263 · WordPress/gutenberg

DAreRodz · 2026-02-05T19:08:38Z

What?

Adds a "Core Concepts" guide for the Interactivity Router.

Why?

The Interactivity Router, while being documented in the README, lacked an in-depth explanation about how it works.

How?

The document follows this structure:

Client-Side Navigation
- How client-side navigation works
- Getting started with the Interactivity Router
  - Setting up router regions
  - Implementing navigation
  - Implementing prefetching
  - Complete example: Pagination
- Block compatibility
  - The supports.interactivity field
  - Non-interactive blocks
  - Interactive blocks using the Interactivity API
  - Interactive blocks using other libraries
- More advanced use cases
  - Adding new regions on navigation
  - Handling server state updates
  - Overriding cached pages
  - Using custom HTML
  - Managing browser history
  - Changing the timeout
  - Handling fetch errors
  - Disabling client-side navigation on certain pages
  - Disabling navigation feedback
  - Subscribing to page changes
- The Interactivity Router in depth
  - The page cache
  - Router regions
  - CSS handling
  - Script module handling
  - Server state and context
  - Putting it all together: the navigation flow
    - Phase 1: Prefetch (optional but recommended)
    - Phase 2: Navigate
    - Race condition protection
- Full-page client-side navigation (experimental)

docs/reference-guides/interactivity-api/core-concepts/client-side-navigation.md

github-actions · 2026-02-13T12:01:08Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: DAreRodz <darerodz@git.wordpress.org>
Co-authored-by: luisherranz <luisherranz@git.wordpress.org>
Co-authored-by: juanmaguitar <juanmaguitar@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

luisherranz

Amazing work so far, David! The guide is very well understood and covers a lot of topics.

For now, I've reviewed everything in depth up to the "Interactivity Router in depth" part, which I'll do on Monday, but that part looks very good too.

I'm adding a few comments here, and besides that, two other suggestions:

Adding a link to this guide in the interactivity-router README, prominently at the top, since there may be users who end up there and, in reality, should always read this guide.
Adding a section explaining that neither the scroll nor the focus are handled by the router, and that they are the responsibility of the action calling actions.navigate.

docs/reference-guides/interactivity-api/iapi-about.md

luisherranz · 2026-02-13T13:37:05Z

docs/reference-guides/interactivity-api/core-concepts/client-side-navigation.md

+```bash
+npx @wordpress/create-block@latest my-interactive-block --template @wordpress/create-block-interactive-template
+```


@juanmaguitar, weren't you working on a template for client-side navigation? Could it be?

I think you may refer to the example I was working on for the block development examples:
https://github.com/WordPress/block-development-examples/tree/trunk/plugins/interactivity-router-2f43f8

But it would be great to have a template for client-side-navigation. In fact, we could expand the existing @wordpress/create-block-interactive-template with a new variant for clien-side navigation (now it's easier because each variant can have its own structure of files #67768)

Nice. Thanks Juanma 🙂

docs/reference-guides/interactivity-api/core-concepts/client-side-navigation.md

luisherranz · 2026-02-13T14:05:09Z

docs/reference-guides/interactivity-api/core-concepts/client-side-navigation.md

+### Disabling navigation feedback
+
+The Interactivity API router includes built-in feedback during navigation:
+- **Loading animation**: A progress bar that appears during navigation.


It would be good to specify here what color is used for this bar, which I think is a CSS variable, like --color-primary or something like that?

Woops, it looks like the loading bar is not using any CSS variables... 👀

https://github.com/WordPress/wordpress-develop/blob/45e2aee38fa50cb8a7f60713c390d3f963e17eea/src/wp-includes/interactivity-api/class-wp-interactivity-api.php#L1247

That's interesting. Maybe we had it in the first versions and we forgot to copy it during some migration? I'll put it on the roadmap.

docs/reference-guides/interactivity-api/core-concepts/client-side-navigation.md

DAreRodz · 2026-02-16T15:24:43Z

@luisherranz, I think I've addressed all your feedback, including your suggestions:

A "Handling scroll and focus" section in 7c6987c.
A link to this guide inside the Router's README in e06e9ca.

docs/reference-guides/interactivity-api/core-concepts/client-side-navigation.md

luisherranz

I've made some small changes in cc519b1, and here are some other suggestions for the in-depth part, which I think is quite good.

Apart from that, we should remove the section about block compatibility to do it separately and more carefully, and I wonder if we should also create a separate section for full-page client-side navigation.

Finally, I also wonder if we should remove most references to "interactive blocks" and blocks in general, since this also works with classic PHP themes.

docs/reference-guides/interactivity-api/core-concepts/client-side-navigation.md

github-actions · 2026-02-18T10:09:13Z

Flaky tests detected in 6f8f7d1.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/22636058579
📝 Reported issues:

[Flaky Test] Navigates the items list via UP/DOWN arrow keys #64334 in /test/e2e/specs/site-editor/dataviews-list-layout-keyboard.spec.js

DAreRodz · 2026-02-20T10:11:21Z

@luisherranz, addressed your feedback. I'm doing an extra review of the whole document to make sure everything is fine.

Apart from that, we should remove the section about block compatibility to do it separately and more carefully, and I wonder if we should also create a separate section for full-page client-side navigation.

I removed the block compatibility section. Do you think we should start working on another document to explain block compatibility now?

Regarding full-page client-side navigation, do you mean a new document or a section in the same document? Asking because there's already a section at the end of the document.

Finally, I also wonder if we should remove most references to "interactive blocks" and blocks in general, since this also works with classic PHP themes.

Yup, we could emphasize somewhere in the document that client-side navigation works with classic themes as well.

luisherranz · 2026-02-20T10:16:56Z

Do you think we should start working on another document to explain block compatibility now?

Yes.

Regarding full-page client-side navigation, do you mean a new document or a section in the same document? Asking because there's already a section at the end of the document.

I don't know, maybe it's fine as it is and we can move it in the future if it really deserves its own section.

Yup, we could emphasize somewhere in the document that client-side navigation works with classic themes as well.

Good idea. We could add a section at the beginning stating that it works with both blocks and classic themes. In fact, I'd like to make that much clearer throughout the documentation, as it currently seems like the Interactivity API only works with blocks.

In principle, here I think we should just delete all the sentences that talk about interactive blocks, which in a way assume that this only works in interactive blocks, and only leave the mentions of interactive blocks for things specific to them (supports.interactivity, etc.).

juanmaguitar · 2026-02-25T10:48:49Z

Apart from that, we should remove the section about block compatibility to do it separately and more carefully, and I wonder if we should also create a separate section for full-page client-side navigation.

What do you think about creating a new "Client Side Navigation" page under the iAPI docs root and inside of it another doc called "Block Compatibility Guide"

The new structure would like this:

Interactivity API Reference

Core Concepts
- The Reactive and Declarative mindset
- Understanding global state, local context, derived state and config
- Server-side rendering: Processing directives on the server
- Using TypeScript
Client Side Navigation 🆕
- Block Compatibility Guide 🆕
Quick start guide
Directives and Store
About the Interactivity API
Frequently Asked Questions

Maybe this new "Client Side Navigation" page could also tackle #56638

luisherranz · 2026-02-25T12:26:08Z

I love the idea. Maybe we could also include one about Full-page client-side navigation in the future.

DAreRodz · 2026-02-27T12:35:15Z

I also like the idea. 😄

I think It would be a good opportunity to divide the guide (~1000 lines) in multiple documents.

@juanmaguitar, how would the structure be exactly? A folder named client-side-navigation with a README.md file containing the rest of the documents?

interactivity-api/
├── ...
└── client-side-navigation/
    ├── client-side-navigation-block-compatibility.md
    ├── client-side-navigation-in-depth.md
    ├── client-side-navigation-quick-start-guide.md
    ├── client-side-navigation-reference.md
    └── README.md

luisherranz

I just pushed some minor changes. It would be great if you could review it.

Apart from that:

We should include information about data-wp-key and how to use that directive so that lists work correctly when navigating.
We should also add information about how to inject data-wp-router-options='{"loadOnClientNavigation": true}' attribute using the PHP APIs (wp_interactivity()->add_client_navigation_support_to_script_module), and when it's automatically added (blocks with supports.interactivity).

luisherranz

LGTM! ❤️

Awesome work, David. This is a really, really good guide.

DAreRodz mentioned this pull request Feb 5, 2026

Docs: Interactivity API - Create a Core Concepts section for the iAPI #62921

Open

9 tasks

DAreRodz added [Type] Developer Documentation Documentation for developers [Feature] Interactivity API API to add frontend interactivity to blocks. labels Feb 5, 2026

juanmaguitar reviewed Feb 12, 2026

View reviewed changes

docs/reference-guides/interactivity-api/core-concepts/client-side-navigation.md Outdated Show resolved Hide resolved

DAreRodz marked this pull request as ready for review February 13, 2026 12:00

DAreRodz requested review from ajitbohra and fabiankaegy as code owners February 13, 2026 12:00

DAreRodz requested a review from luisherranz February 13, 2026 12:01

luisherranz requested changes Feb 13, 2026

View reviewed changes

github-actions bot added the [Package] Interactivity Router /packages/interactivity-router label Feb 16, 2026

luisherranz reviewed Feb 17, 2026

View reviewed changes

docs/reference-guides/interactivity-api/core-concepts/client-side-navigation.md Outdated Show resolved Hide resolved

luisherranz reviewed Feb 17, 2026

View reviewed changes

docs/reference-guides/interactivity-api/core-concepts/client-side-navigation.md Outdated Show resolved Hide resolved

luisherranz reviewed Feb 18, 2026

View reviewed changes

luisherranz requested changes Mar 3, 2026

View reviewed changes

DAreRodz added 8 commits March 3, 2026 18:40

Add initial version of the guide

ed01d0f

Update overall content and structure

e61b98c

Improve "In depth" section

f7fc8b1

Add clarification for HTML outside router regions

bd7318a

Move "In Depth" section to the end

c56a939

Add reference to router's README

ac99fac

Improve basic example

1792825

Fix "handling fetch errors" example

1e9222b

DAreRodz and others added 22 commits March 3, 2026 18:40

Fix callout mentioning how CSN is automatically disabled

749163c

Updated global-state-local-context references

f5e2d6b

Clarify cache override

9ec56dd

Clarify timeout behavior

a37a10a

Remove "interactive blocks using the iAPI" section

0b8772b

Remove hasStarted/hasFinished mention

ae9b937

Rewrite intro with bullet points

b31b405

Clarify navigation trigger

9dbdf95

Add "Handling scroll and focus" section

77929d0

Add state.url limitation note

869ea8d

A few changes

6f0c757

Remove dashboard example in "disabling CSN"

88a1d74

Rewrite "subscribing to page changes" section

237f61d

Fix formatting

94c674e

Move router region requirements to Getting Started section

a352d67

Reword script modules preloading explanation

ebb7832

Mention CSS and JS downloading in region processing section

c701771

Remove block compatibility section

b0717ae

Clarify CSN works with classic themes

ecce0a5

Some minor changes

dd2fdc7

Add "Ensuring script modules load" section

d6b9b4f

Refactor the Getting Started section's structure

6f8f7d1

DAreRodz force-pushed the docs/iapi-client-side-navigation-guide branch from 469b49d to 6f8f7d1 Compare March 3, 2026 17:56

Add section for data-wp-key

9668685

luisherranz approved these changes Mar 3, 2026

View reviewed changes

luisherranz merged commit e2d2a56 into trunk Mar 3, 2026
39 checks passed

luisherranz deleted the docs/iapi-client-side-navigation-guide branch March 3, 2026 22:35

github-actions bot added this to the Gutenberg 22.7 milestone Mar 3, 2026

luisherranz mentioned this pull request Mar 5, 2026

[iAPI Router / AJAX Navigation] WooCommerce cart, checkout, and my-account pages fail to rehydrate scripts after SPA swap — forces full page reload woocommerce/woocommerce#63518

Open

juanmaguitar mentioned this pull request Mar 10, 2026

Add Client-Side Navigation documentation to manifest and table of contents #76351

Merged

Conversation

DAreRodz commented Feb 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What?

Why?

How?

Uh oh!

Uh oh!

github-actions bot commented Feb 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

luisherranz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

luisherranz Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

juanmaguitar Feb 23, 2026

Choose a reason for hiding this comment

Uh oh!

luisherranz Feb 24, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

luisherranz Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

DAreRodz Feb 16, 2026

Choose a reason for hiding this comment

Uh oh!

luisherranz Feb 17, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

DAreRodz commented Feb 16, 2026

Uh oh!

Uh oh!

Uh oh!

luisherranz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Feb 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

DAreRodz commented Feb 20, 2026

Uh oh!

luisherranz commented Feb 20, 2026

Uh oh!

juanmaguitar commented Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

luisherranz commented Feb 25, 2026

Uh oh!

DAreRodz commented Feb 27, 2026

Uh oh!

luisherranz left a comment

Choose a reason for hiding this comment

Uh oh!

luisherranz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

DAreRodz commented Feb 5, 2026 •

edited

Loading

github-actions bot commented Feb 13, 2026 •

edited

Loading

github-actions bot commented Feb 18, 2026 •

edited

Loading

juanmaguitar commented Feb 25, 2026 •

edited

Loading