iAPI Docs: Add client-side navigation compatibility guide by DAreRodz · Pull Request #76242 · WordPress/gutenberg

DAreRodz · 2026-03-06T11:27:43Z

What?

Adds a new documentation page: Client-Side Navigation Compatibility Guide for the Interactivity API.

Why?

Block developers and theme authors need clear guidance on what makes their code compatible with client-side navigation. Without this, developers may unknowingly introduce patterns that break client-side navigation — causing fallbacks to full page reloads or potentially breaking the site, degrading the user experience.

There was no centralized reference for CSN compatibility, nor a checklist that developers could use to verify compatibility before declaring their blocks compatible.

How?

Adds a new document at docs/reference-guides/interactivity-api/core-concepts/client-side-navigation-compatibility.md and links it from the Core Concepts README. The guide covers:

Declaring compatibility in block.json via supports.interactivity.clientNavigation.
What makes a block compatible — non-interactive blocks, Interactivity API blocks, and blocks using other libraries.
CSS requirements — no dynamic CSS injection, no runtime stylesheet modifications, stable CSS selectors (with wp_unique_id_from_values() as the recommended alternative to wp_unique_id()), and selector consistency across navigations.
JavaScript requirements — use of script modules instead of regular scripts, and how to handle script modules outside blocks (e.g., classic PHP themes) via wp_register_script_module() with loadOnClientNavigation.
HTML requirements — consistent HTML structures, proper use of data-wp-key for dynamic lists, avoiding DOM mutations outside the Interactivity API (with data-wp-watch as the escape hatch), and using attachTo for HTML outside router regions.
Compatibility checklist — a pre-flight checklist for developers to verify before marking a block as CSN-compatible.
Quick reference table summarizing block types and their compatibility status.

The guide is written to be useful for both block developers and classic PHP theme/plugin authors.

github-actions · 2026-03-09T16:37:48Z

Flaky tests detected in e390127.
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/23620565336
📝 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
[Flaky Test] Should render and migrate legacy openSubmenusOnClick blocks #75559 in /test/e2e/specs/editor/blocks/navigation-frontend-interactivity.spec.js
[Flaky Test] post title and content are editable and blocks can be inserted #76524 in /test/e2e/specs/editor/various/post-content-focus-mode.spec.js

github-actions · 2026-03-10T16:44:40Z

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: ryanwelcher <welcher@git.wordpress.org>

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

ryanwelcher · 2026-03-11T16:43:24Z

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

+
+Accessing WordPress packages through global variables like `window.wp.element` or `window.wp.data` is not compatible with CSN. These globals are set by regular scripts, which are not re-executed during client-side navigation.
+
+**Instead:** Use ES module imports from the corresponding `@wordpress/*` script module, if one is available. For example, `@wordpress/a11y` is available both as a regular script (`window.wp.a11y`) and as a script module:


Is there a definitive list of which packages are compatble?

luisherranz

I added a bunch of corrections and refinements in a6bbb97. Can you review them to make sure they are all correct?

I added cross-references to the CSN Compatibility guide across the documentation for better discoverability:

Client-Side Navigation guide: Added a callout near the top of the page, and a link in the "Ensuring script modules load during navigation" section where clientNavigation in block.json is explained.
Router package README: Extended the existing callout to also mention the compatibility guide.
Block Supports reference: Simplified the clientNavigation sub-property description to defer to the compatibility guide instead of inlining partial guidelines.
Interactivity API FAQ: Linked the "client-side navigation" mention to the CSN guide.
toc.json and manifest.json: Added entries for both the Client-Side Navigation guide and the Client-Side Navigation Compatibility guide, which were missing from the handbook's table of contents and manifest.

And other things that I think should be clarified below.

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

…mentation

…ntation

…avigation documentation

luisherranz

Thanks for the changes, David 🙂

LGTM now! Approving 👍

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

DAreRodz marked this pull request as ready for review March 10, 2026 16:44

DAreRodz requested review from ajitbohra, fabiankaegy and juanmaguitar as code owners March 10, 2026 16:44

ryanwelcher reviewed Mar 11, 2026

View reviewed changes

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

luisherranz requested changes Mar 25, 2026

View reviewed changes

DAreRodz and others added 19 commits March 26, 2026 21:55

Add initial guide

b239beb

Apply some corrections

27eaace

Update format

6df30fa

Add minor clarification regarding data-wp-key usage

4f7c570

Apply some improvements

e476532

Fix explanation for csn support in script modules

f24ec2d

Fix references to data-wp-watch and reactive state concepts

b4d5eb1

Add missing JS-related points

ee666df

Fix reference to attachTo

68b940b

Update opening paragraph

2545d74

Update lists order

98e9408

Fix analytics example

8871978

Add new guide to toc and manifest

28f1494

Update iAPI router's README to include link to the compatibility guide

a213a06

Clarify clientNavigation compatibility details in block supports docu…

babd8a1

…mentation

Update Interactivity API FAQ to link to client-side navigation docume…

0492d09

…ntation

A bunch of corrections and refinements

3a354f2

Add compatibility guide link to client-side navigation documentation

02a1df0

Clarify compatibility details for classic PHP themes in client-side n…

242afb9

…avigation documentation

DAreRodz force-pushed the docs/iapi-csn-compatibility-guide branch from 12930f7 to 242afb9 Compare March 26, 2026 20:56

DAreRodz added 6 commits March 26, 2026 22:33

Fix the clientNavigation callout info

73f6888

Remove "generally" for non-interactive blocks description

3ce0e76

Add missing "or"

7e2c1b2

Remove "handle CSS animations and transitions"

f022635

Fix "Ensuring compatibility" intro

a9bbc9f

Remove duplicated client-side navigation entry in toc and manifest files

e390127

DAreRodz requested a review from luisherranz March 26, 2026 22:35

luisherranz approved these changes Mar 27, 2026

View reviewed changes

luisherranz merged commit 884c9e0 into trunk Mar 27, 2026
56 of 61 checks passed

luisherranz deleted the docs/iapi-csn-compatibility-guide branch March 27, 2026 06:22

github-actions bot added this to the Gutenberg 22.9 milestone Mar 27, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

iAPI Docs: Add client-side navigation compatibility guide#76242

iAPI Docs: Add client-side navigation compatibility guide#76242
luisherranz merged 25 commits intotrunkfrom
docs/iapi-csn-compatibility-guide

DAreRodz commented Mar 6, 2026

Uh oh!

github-actions bot commented Mar 9, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Mar 10, 2026 •

edited

Loading

Uh oh!

ryanwelcher Mar 11, 2026

Uh oh!

luisherranz left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

luisherranz left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		Accessing WordPress packages through global variables like `window.wp.element` or `window.wp.data` is not compatible with CSN. These globals are set by regular scripts, which are not re-executed during client-side navigation.

		Instead: Use ES module imports from the corresponding `@wordpress/*` script module, if one is available. For example, `@wordpress/a11y` is available both as a regular script (`window.wp.a11y`) and as a script module:

Conversation

DAreRodz commented Mar 6, 2026

What?

Why?

How?

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

ryanwelcher Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

luisherranz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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

github-actions bot commented Mar 9, 2026 •

edited

Loading

github-actions bot commented Mar 10, 2026 •

edited

Loading