Skip to content

Boot: Maintain focus within page region when router changes page - #86701

Merged
aduth merged 3 commits into
trunkfrom
fix/boot-router-focus-loss
Nov 19, 2026
Merged

aduth merged 3 commits into
trunkfrom
fix/boot-router-focus-loss

Conversation

@aduth

@aduth aduth commented Nov 11, 2026

Copy link
Copy Markdown
Member

What?

Fixes #86700

Updates @wordpress/boot so that if a router navigation would result in a focus loss, focus is instead moved to the new route's stage container.

Why?

So that focus is not lost when navigating between pages.

How?

A hook in the Root component observes route changes after initial mount and redirects focus to the layout's region if a route change would result in otherwise resetting to the document's body element.

Testing Instructions

Repeat Steps to Reproduce in #86700, observing the expected result.

Use of AI Tools

Researched and implemented in coordination with Claude Code + Opus 5.5.

@aduth aduth added [Type] Bug An existing feature does not function as intended [Focus] Accessibility (a11y) Changes that impact accessibility and need corresponding review (e.g. markup changes). labels Nov 11, 2026
@aduth aduth added the Needs Accessibility Feedback Need input from accessibility label Nov 11, 2026
Comment on lines +40 to +44
layout
.querySelector< HTMLElement >(
`.${ styles.stage } [role="region"]`
)
?.focus();

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's a bit of an implicit dependency here. While it's conventional to use Page in the route stage, there's nothing to say that it must be. And so this query is largely targeting Page's NavigableRegion. But I think even though it's a loose dependency, (a) it's reasonable to use the first matched region as the semantic landmark to target, and (b) it fails gracefully if it can't be found.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wondering if the fallback should be [role="main"] or <main>? 🤔 Might be too magical.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wondering if the fallback should be [role="main"] or <main>? 🤔 Might be too magical.

The short answer is: probably not. The longer answer is a huge can of worms 😅 tl;dr is that Page doesn't render <main>, and sometimes <main> doesn't exist at all. Sometimes wp-admin applies role=main on div#wpbody. But main is also unnamed. There's probably some improvements that ought to be done here, since there's cases where no main exists at all, but the short of it here is that we probably want to keep this as focused on the regions. It's also the case that there are multiple "stages" in a page, each one is a region, and each one can render in a way that causes focus loss.

Was there something in particular you were hoping would be improved with that alternative?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess to the original point, if we can't guarantee Page renders a region, but there's a stronger guarantee of a main, then main could be a next logical fallback. But it seems we can't necessarily guarantee there's a main either.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Page doesn't render <main>

Related: I discovered that #77628 mentions this as a proposed improvement to Page:

Correct semantics by default. <main> landmark [...]

@github-actions

github-actions Bot commented Nov 11, 2026 •

Copy link
Copy Markdown

🤖 PR meta 🤖

🎉 Props

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: aduth <aduth@git.wordpress.org>
Co-authored-by: simison <simison@git.wordpress.org>
Co-authored-by: t-hamano <wildworks@git.wordpress.org>
Co-authored-by: jameskoster <jameskoster@git.wordpress.org>

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


Props Bot commands

You can trigger Props Bot actions by commenting on this PR:

  • @propsbot add <username> to give props to a GitHub user. Requires write access.
  • @propsbot remove <username> to leave a user out of the props. Requires write access.
  • @propsbot refresh to refresh this list. Adding the props-bot label works too.

Updated as activity occurs, without notifying anyone named here. Add the props-bot label to refresh.

📦 Bundle size

Size Change: +460 B (+0.01%)

Total Size: 8.68 MB

📦 View Changed
Filename Size Change
build/modules/boot/index.min.js 51.7 kB +460 B (+0.9%)

cc78f7e Run

⚡ Performance

Show the results

Client side metrics exclude the server response time.

front-end-block-theme

Metric 6d2e040 trunk % Change
timeToFirstByte 45.45 ms +5.5% -2.97% 46.15 ms +5.2% -3.58% -1.52%
largestContentfulPaint 72 ms +5.56% -5.56% 72 ms +11.11% -5.56% 0%
lcpMinusTtfb 25.35 ms +8.28% -5.33% 25.3 ms +30.63% -7.11% 0.2%
wpBeforeTemplate 23.27 ms +3.95% -6.7% 23.19 ms +5.17% -4.4% 0.34%
wpTemplate 18.99 ms +3.58% -2.95% 18.63 ms +6.71% -1.61% 1.93%
wpTotal 41.81 ms +5.33% -2.89% 42.14 ms +5.41% -3.06% -0.78%
wpMemoryUsage 7.75 MB +0% -0% 7.71 MB +0% -0% 0.46%
wpDbQueries 16 +0% -0% 16 +0% -0% 0%

front-end-classic-theme

Metric 6d2e040 trunk % Change
timeToFirstByte 37.85 ms +3.96% -4.62% 37.25 ms +5.37% -2.95% 1.61%
largestContentfulPaint 68 ms +8.82% -0% 68 ms +5.88% -2.94% 0%
lcpMinusTtfb 31.65 ms +3.32% -5.69% 30.45 ms +7.39% -5.91% 3.94%
wpBeforeTemplate 20.43 ms +4.26% -4.26% 19.97 ms +5.61% -4.21% 2.3%
wpTemplate 14.25 ms +5.47% -4.35% 14.7 ms +3.54% -5.37% -3.06%
wpTotal 35.07 ms +3.11% -5.36% 34.21 ms +5.7% -2.34% 2.51%
wpMemoryUsage 6.44 MB +0% -0% 6.40 MB +0% -0% 0.56%
wpDbQueries 13 +0% -0% 13 +0% -0% 0%

media-processing

Metric 6d2e040 trunk % Change
mediaProcessingJpeg 362.39 ms +1.98% -2.39% 354.96 ms +4.12% -1.39% 2.09%
mediaProcessingAvif 5359.78 ms +2.2% -0.77% 5258.98 ms +0.87% -0.06% 1.92%
mediaProcessingJpegToAvif 3600.4 ms +0.99% -0.24% 3591.06 ms +0.79% -0.15% 0.26%

media-upload

Metric 6d2e040 trunk % Change
jpegUploadProcessing 1471.08 ms +34.77% -0.56% 1452.82 ms +1.91% -0.82% 1.26%
pngUploadProcessing 237.67 ms +6.21% -3.5% 231.82 ms +8.63% -5.2% 2.52%
largeJpegUploadProcessing 1446.23 ms +0.78% -0.32% 1445.06 ms +0.69% -0.77% 0.08%
multipleImageUploadProcessing 1530.04 ms +2.42% -0.89% 1527.65 ms +1.58% -0.54% 0.16%

post-editor

Metric 6d2e040 trunk % Change
serverResponse 415.38 ms +0.42% -8.12% 414.8 ms +2.2% -8.46% 0.14%
firstPaint 433.77 ms +20.39% -6.81% 417.29 ms +5.42% -8.51% 3.95%
domContentLoaded 795.74 ms +9.2% -1.83% 801.83 ms +0.71% -2.32% -0.76%
loaded 796.72 ms +9.2% -1.81% 802.77 ms +0.73% -2.28% -0.75%
firstContentfulPaint 457.37 ms +15.26% -4.31% 445.95 ms +1.94% -1.55% 2.56%
firstBlock 2046.45 ms +4.97% -1.7% 2039.46 ms +2.16% -1.08% 0.34%
type 16.64 ms +4.03% -13.58% 17.28 ms +3.53% -7.75% -3.7%
typeWithoutInspector 16.85 ms +9.73% -9.91% 16.98 ms +4.06% -12.96% -0.77%
typeWithTopToolbar 22.68 ms +2.65% -11.99% 22.97 ms +6.49% -8.53% -1.26%
typeContainer 7.79 ms +12.84% -10.4% 7.93 ms +6.56% -14.63% -1.77%
focus 120.65 ms +5.12% -1.52% 117.3 ms +3.9% -3.1% 2.86%
firstFocus 259.05 ms +0% -0% 258.43 ms +0% -0% 0.24%
selectAll 351.65 ms +1.07% -1.67% 346.7 ms +0.12% -2.6% 1.43%
undo 29.03 ms +5.96% -6.44% 30.81 ms +3.21% -8.47% -5.78%
listViewOpen 72.72 ms +4.99% -1.99% 72.3 ms +10.12% -3.53% 0.58%
inserterOpen 44.79 ms +4.98% -15.96% 42.11 ms +4.87% -6.36% 6.36%
inserterHover 12.04 ms +7.48% -7.81% 11.6 ms +7.59% -8.28% 3.79%
inserterSearch 8.23 ms +5.1% -3.28% 8.37 ms +9.32% -8.6% -1.67%
loadPatterns 681.1 ms +3.86% -4.95% 715.77 ms +1.66% -6.69% -4.84%
wpTotal 405.83 ms +0.47% -8.31% 405.6 ms +1.99% -8.64% 0.06%
wpMemoryUsage 14.81 MB +0% -0% 14.77 MB +0% -0% 0.25%
wpDbQueries 55 +0% -0% 55 +0% -0% 0%

site-editor

Metric 6d2e040 trunk % Change
serverResponse 388.72 ms +0.82% -7.63% 376.57 ms +2.84% -5.03% 3.23%
firstPaint 443.28 ms +3.68% -17.89% 403.45 ms +11.61% -4.77% 9.87%
domContentLoaded 795.28 ms +0.97% -1.58% 787.81 ms +0.37% -0.58% 0.95%
loaded 796.37 ms +0.94% -1.59% 788.71 ms +0.36% -0.59% 0.97%
firstContentfulPaint 445.03 ms +3.27% -1.18% 448.24 ms +0.64% -2.22% -0.72%
firstBlock 2320.24 ms +2.85% -0.56% 2297.31 ms +1.85% -0.81% 1%
type 16.8 ms +10.06% -8.63% 17.22 ms +5.4% -10.45% -2.44%
navigate 103.91 ms +9.65% -2.07% 102.86 ms +12.05% -1.71% 1.02%
loadPatterns 1230.23 ms +10.63% -1.43% 1230.07 ms +6.82% -7.05% 0.01%
loadPages 914.04 ms +2.83% -2.06% 910.8 ms +1.25% -1.11% 0.36%
wpTotal 379.41 ms +0.8% -7.83% 367.13 ms +2.88% -5.17% 3.34%
wpMemoryUsage 12.82 MB +0% -0% 12.79 MB +0% -0% 0.25%
wpDbQueries 45 +0% -0% 45 +0% -0% 0%

cc78f7e Run

🏁 Flaky tests

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.

should allow user to add and remove multiple local font files in /test/e2e/specs/admin/font-library.spec.js, passed after 1 failed attempt.
Error: expect(locator).toBeVisible() failed

Locator: getByLabel('Exo 2 Semi-bold Italic')
Expected: visible
Timeout: 5000ms
Error: element(s) not found

Call log:
  - Expect "toBeVisible" getByLabel('Exo 2 Semi-bold Italic') with timeout 5000ms
  - waiting for getByLabel('Exo 2 Semi-bold Italic')

    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/admin/font-library.spec.js:58:6
templates can be registered and edited (Site Editor v2) in /test/e2e/specs/site-editor/template-registration.spec.js, passed after 1 failed attempt.
Error: expect(locator).toBeVisible() failed

Locator: getByText('AuthorGutenberg')
Expected: visible
Error: strict mode violation: getByText('AuthorGutenberg') resolved to 3 elements:
    1) <div data-wp-c16t="true" data-wp-component="Flex" class="_463056a1846babdd__flex eefcc0383f58d3a1__items-row _8a741740b23dfb57__expanded-row components-flex dataviews-view-grid__field">…</div> aka getByRole('row', { name: 'Row 1' }).getByText('AuthorGutenberg')
    2) <div data-wp-c16t="true" data-wp-component="Flex" class="_463056a1846babdd__flex eefcc0383f58d3a1__items-row _8a741740b23dfb57__expanded-row components-flex dataviews-view-grid__field">…</div> aka locator('[id="emptytheme//page"]').getByText('AuthorGutenberg')
    3) <div data-wp-c16t="true" data-wp-component="Flex" class="_463056a1846babdd__flex eefcc0383f58d3a1__items-row _8a741740b23dfb57__expanded-row components-flex dataviews-view-grid__field">…</div> aka locator('[id="emptytheme//plugin-template"]').getByText('AuthorGutenberg')

Call log:
  - Expect "toBeVisible" getByText('AuthorGutenberg') with timeout 5000ms
  - waiting for getByText('AuthorGutenberg')

    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/site-editor/template-registration.spec.js:60:55

cc78f7e Run

@simison simison added the [Package] Boot /packages/boot label Nov 12, 2026
@simison

simison commented Nov 12, 2026

Copy link
Copy Markdown
Member

These might not be worth adding as test, but I checked the logic works also across these scenarios with the router:

  • A route whose beforeLoad throws redirect (expect focus in the destination region).
  • A route whose loader throws a plain error.
  • A route that sets stage: false or uses a stage without Page.

Comment thread packages/boot/CHANGELOG.md Resolved
@jameskoster

Copy link
Copy Markdown
Contributor

This works nicely with the Settings Page patterns in #86451, which I've aligned to focus the Page region the same way. Two things came up while testing:

  1. Unnamed regions on subpages. Page derives its region's aria-label from a string title. Subpages that show breadcrumbs instead of a title get an empty label, so after following a breadcrumb or a subpage link, screen readers announce focus on an unnamed region. The test fixtures pass ariaLabel explicitly, which hides this. Could Page fall back to the current (last) breadcrumb, or should we document that pages with breadcrumbs need ariaLabel?
  2. Section navigation. Pages with Page navigation render the nav inside each route's stage, so switching sections also removes the focused link, and focus moves to the region. Keeping focus on the newly current nav item would let keyboard users carry on through the sections. Not a blocker, just worth considering.

@aduth

aduth commented Nov 12, 2026

Copy link
Copy Markdown
Member Author

The end-to-end test failures demonstrate a real challenge, which is that this can potentially conflict with other focus management that happens. The test failure is related to some DataViews behavior where clicking a "Cancel" button causes a page navigation, but DataViews itself tries to maintain focus, and only in the same reset-to-<body> scenario that we're covering here. Thus, they conflict with one another. I'll put some thought into how best to address this.

@aduth

aduth commented Nov 12, 2026

Copy link
Copy Markdown
Member Author

These might not be worth adding as test, but I checked the logic works also across these scenarios with the router:

@simison Maybe we could have at least one test covering the "did not actually redirect so don't do anything with focus" scenario.

The stage: false could be nice to have as well.

  1. Unnamed regions on subpages. Page derives its region's aria-label from a string title. Subpages that show breadcrumbs instead of a title get an empty label [...] Could Page fall back to the current (last) breadcrumb, or should we document that pages with breadcrumbs need ariaLabel?

@jameskoster My sense here is that there being a region without a label is a problem irrespective of what we do with focus. So something like ariaLabel could be something we'd want anyways.

2. Section navigation. Pages with Page navigation render the nav inside each route's stage, so switching sections also removes the focused link, and focus moves to the region. Keeping focus on the newly current nav item would let keyboard users carry on through the sections. Not a blocker, just worth considering.

@jameskoster That's a good point 👍 It's a good example of a case where the same effective element still exists on the page, so it should be able to keep focus. This might actually be more a problem that the navigation is being entirely re-rendered, and we could solve this by making sure React diffs in a way that keeps the navigation elements intact.

jameskoster added a commit that referenced this pull request Nov 13, 2026
Hold navigation until a pending save settles, clear the failed save
notice once there's nothing to retry, name each adjacent page's region,
drop the disabled Save tooltip, and describe focus restoration as
something the example provides until #86701 lands.

Co-authored-by: Cursor <cursoragent@cursor.com>

@t-hamano t-hamano left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The end-to-end test failures demonstrate a real challenge, which is that this can potentially conflict with other focus management that happens. The test failure is related to some DataViews behavior where clicking a "Cancel" button causes a page navigation, but DataViews itself tries to maintain focus

I think this should be fixed on the DataViews side. DataViews decides whether to move focus by checking whether focus fell to the body, not by whether the Cancel button was clicked. Boot reacts to the same state, so both try to recover focus, and Boot wins. #86932 makes DataViews move focus only in response to the interaction, before Boot checks, so it should fix at least this case.

That said, we can't rule out that consumers inject components with their own focus management. What about an approach where Boot only recovers focus if it is still lost after rendering has settled?

@aduth

aduth commented Nov 17, 2026

Copy link
Copy Markdown
Member Author

#86932 makes DataViews move focus only in response to the interaction, before Boot checks, so it should fix at least this case.

Yeah, thanks for splitting that off. I think it makes sense that DataViews can be more direct about handling its own internal expectations and not try to blanket handle focus loss as it is.

What about an approach where Boot only recovers focus if it is still lost after rendering has settled?

Yeah I think we can do this, and as I recall it was a direction my agent was starting to explore when I last left this. I'll pick it up again and see if I can find a solution here.

@aduth
aduth marked this pull request as draft November 17, 2026 18:28
@aduth
aduth force-pushed the fix/boot-router-focus-loss branch from 26e7625 to 79dea85 Compare November 17, 2026 18:28
@aduth

aduth commented Nov 17, 2026 •

Copy link
Copy Markdown
Member Author
  1. Unnamed regions on subpages. Page derives its region's aria-label from a string title. Subpages that show breadcrumbs instead of a title get an empty label, so after following a breadcrumb or a subpage link, screen readers announce focus on an unnamed region. The test fixtures pass ariaLabel explicitly, which hides this. Could Page fall back to the current (last) breadcrumb, or should we document that pages with breadcrumbs need ariaLabel?

Following-up on this now that I have a better understanding:

First, as mentioned above, this is only tangentially related to the pull request, since the fact that there's no guarantee of a label exists already on trunk.

I think your general proposal is right that we should try to read (or refer via aria-labelledby) the name from the last breadcrumb item, since it's effectively the substitute for the heading.

I explored this with a solution that uses React context to pass a heading ID through from Page to the breadcrumb element, and it seems to work alright (see branch).

But then I remembered that the fact that we pass <Breadcrumb> as an element is something I wanted to change per my proposal of "configuration props" in #76709 (comment) . Just like we structured navigation as an object in #79746, my expectation is that we'd move away from <Breadcrumbs> being passed as an element, and pass it as an object instead.

If we did this, we could avoid context altogether and page would have access to the title directly, because it'd be passed as a plain object/array that it could reference, e.g. the name is ariaLabel ?? title ?? lastItem.label.

@aduth

aduth commented Nov 17, 2026

Copy link
Copy Markdown
Member Author
  1. Section navigation. Pages with Page navigation render the nav inside each route's stage, so switching sections also removes the focused link, and focus moves to the region. Keeping focus on the newly current nav item would let keyboard users carry on through the sections. Not a blocker, just worth considering.

@jameskoster That's a good point 👍 It's a good example of a case where the same effective element still exists on the page, so it should be able to keep focus. This might actually be more a problem that the navigation is being entirely re-rendered, and we could solve this by making sure React diffs in a way that keeps the navigation elements intact.

This was quite the deep dive 😅 It's a tricky problem for single-page applications in general, as evidenced by having entire sections devoted to it in HTML specification iterations. I ended up opening #86979 as a separate pull request to explore a solution.

I think we could potentially move forward with this one as an improvement over the status quo. Falling back to the region is at least better than losing focus entirely. #86979 is meant to be additive and make the focus restoration even better, but it could be a follow-on. I created it as a stack so we can review each independently and merge them either together or as a standalone improvements.

@aduth
aduth marked this pull request as ready for review November 17, 2026 20:44
Copilot AI balanced review requested due to automatic review settings November 17, 2026 20:44
@aduth

aduth commented Nov 17, 2026

Copy link
Copy Markdown
Member Author

What about an approach where Boot only recovers focus if it is still lost after rendering has settled?

Yeah I think we can do this, and as I recall it was a direction my agent was starting to explore when I last left this. I'll pick it up again and see if I can find a solution here.

This was implemented in 79dea85, and it appears judging by the tests that it's working now. I don't think this needs to be blocked by #86932, and #86932 is still a worthwhile improvement in its own respect. These changes make it so that the fallback is more accommodating to any manual focus management like DataViews is doing today.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Route focus handling can leave focus on the body after sidebar exit animations or delayed destination mounting because it does not retry when those transitions complete.

2 open issues
What changed in this PR

This PR adds route-change focus recovery to @wordpress/boot, addressing #86700 by moving focus to the destination page region when navigation leaves focus on the document body.

Changes:

  • Integrates a shared focus hook into both root layouts.
  • Adds browser tests for focus recovery, initial loading, retained links, and page-managed focus.
  • Adds test dependencies and documents the fix.
File Description
packages/​boot/​src/​components/​root/​single-page.tsx Enables focus recovery in the single-page layout.
packages/​boot/​src/​components/​root/​index.tsx Enables focus recovery in the main layout.
packages/​boot/​src/​components/​app/​use-route-focus.ts Adds route-change detection and region focusing.
packages/​boot/​src/​components/​app/​test/​navigation-focus.browser.test.tsx Tests navigation focus behavior.
packages/​boot/​src/​components/​app/​test/​fixtures/​settings.tsx Supplies a destination page fixture.
packages/​boot/​src/​components/​app/​test/​fixtures/​settings-general.tsx Supplies navigation links for focus tests.
packages/​boot/​src/​components/​app/​test/​fixtures/​own-focus.tsx Supplies a page that manages its own focus.
packages/​boot/​package.json Declares browser-test dependencies.
packages/​boot/​CHANGELOG.md Documents the focus-recovery fix.
package-lock.json Records the added test dependencies.

Review effort: Balanced

Comment on lines +42 to +44
const { activeElement, body } = layout.ownerDocument;
if ( activeElement && activeElement !== body ) {
return;
Comment on lines +47 to +51
layout
.querySelector< HTMLElement >(
`.${ styles.stage } [role="region"]`
)
?.focus();
@aduth

aduth commented Nov 17, 2026

Copy link
Copy Markdown
Member Author

Those Copilot review comments are yet-more tricky (and real) scenarios to deal with 😅 Both touching on "delayed" rendering of a page. We could still choose to move forward with this as-is for handling the simple case.

One possible option for addressing those together could be using a MutationObserver to continue watching for DOM changes after a navigation, restoring focus if the DOM changes and there's a known target we could focus, and stop watching once some focus has happened (either from focus restoration or the user themselves moving focus).

@aduth

aduth commented Nov 17, 2026

Copy link
Copy Markdown
Member Author
  1. Unnamed regions on subpages. Page derives its region's aria-label from a string title. Subpages that show breadcrumbs instead of a title get an empty label, so after following a breadcrumb or a subpage link, screen readers announce focus on an unnamed region. The test fixtures pass ariaLabel explicitly, which hides this. Could Page fall back to the current (last) breadcrumb, or should we document that pages with breadcrumbs need ariaLabel?

[...]

But then I remembered that the fact that we pass <Breadcrumb> as an element is something I wanted to change per my proposal of "configuration props" in #76709 (comment) . Just like we structured navigation as an object in #79746, my expectation is that we'd move away from <Breadcrumbs> being passed as an element, and pass it as an object instead.

If we did this, we could avoid context altogether and page would have access to the title directly, because it'd be passed as a plain object/array that it could reference, e.g. the name is ariaLabel ?? title ?? lastItem.label.

Following-up on this separately in #86982

@t-hamano

Copy link
Copy Markdown
Contributor

One possible option for addressing those together could be using a MutationObserver to continue watching for DOM changes after a navigation, restoring focus if the DOM changes and there's a known target we could focus, and stop watching once some focus has happened (either from focus restoration or the user themselves moving focus).

I'm not very experienced with SPA routing, so this may be off the mark, but what about adding a focusable wrapper as a fallback for when the region doesn't exist yet?

The router Gatsby uses takes a similar approach, focusing a wrapper like this whenever the URL changes: https://github.com/gatsbyjs/reach-router/blob/bc0302d8304282efc496410931e11ed4ded31c42/src/lib/focus-handler.js#L88-L93

The wrapper itself has no accessible name, but as long as the route defines a title, use-route-title.ts should still announce the new page to screen readers.

That said, this PR is already a big improvement over trunk, so it might be fine to handle this in a follow-up PR 🤔

@aduth

aduth commented Nov 18, 2026

Copy link
Copy Markdown
Member Author

I'm not very experienced with SPA routing, so this may be off the mark, but what about adding a focusable wrapper as a fallback for when the region doesn't exist yet?

I think we could, and it's kinda the idea we're already trying to do here between this pull request and #86979, which is: Try to maintain focus on the same element between page transitions, and fall back up the chain until we can find something that's maintained between the transitions.

I had AI sketch out an illustration to help visualize this chain for myself:

image

The idea with using Page here as the fallback is that it's already a designated region with a name, but the challenge is that the Page is rendered by each route and it can happen asynchronously ¹ . Your idea of using a focusable wrapper could be a next step in the chain, since boot does manage the "stages", and each stage could be a focusable fallback. The spoken announcement in useRouteTitle helps, but it's ephemeral, and we may still want to make sure that the element itself has a name. Perhaps we could label is using the route's title ² . It's also worth noting that we still have to handle the animation delay regardless.

The fact that the stage wrapper and page components are at almost the same place in the DOM does make me wonder if it'd be better to shift the region and labeling up to the stage container itself, and then Page is just a plain UI element that has no semantics of its own. That changes how we've thought about what it is (re: #77628, cc @ciampo ), but maybe in a way that makes sense: Each stage could semantically be a region. Unfortunately it's not entirely straightforward today because the stage itself is removed and re-added via changes in #72937 (cc @youknowriad), so we'd still have to manage focus across route rendering as we do now, maybe just with less concern for asynchronicity. Separately, we might want to revisit this and make sure that the stage remains between rendering, as it did prior to #72937.

Another observation with all this is that there's at least 4 different places that "the page's title" can come from in client-side code: (1) the route title configuration, (2) the Page title prop, (3) the last breadcrumb item's label in a Page breadcrumb, and (4) the Page ariaLabel. I think similar to the point above about semantic roles, there might be an opportunity to simplify how we think of titles between routes and their Page component. Maybe Page should be even more UI-focused, leaving both title and region semantics to the route managed by boot. And if we did that, and we knew stage would persist across navigation transitions, we'd have more guarantees of a named, focusable region that we could direct focus.

Another benefit of this is that we wouldn't need the implicit dependency between @wordpress/boot and @wordpress/admin-ui, since everything around this would happen in boot.

With the brain dump out of the way, here's what I'd propose:

  1. We merge this more or less as-is, as an improvement over the complete focus loss that happens today
  2. Separately, we explore moving some of the existing Page semantics out of Page and into the route: move role=region from Page to stage, and remove title. Page becomes less about semantics and more about common UI arrangement. This impacts Admin UI: Proposal — redesign @wordpress/admin-ui as a focused admin-page framework (2.0) #77628 and should be discussed there.
  3. At some point along the way, we at least still need to handle animations. There's a few ways we could do this, either forcing blur on the animated navigation immediately so the boot handling kicks-in, or handling animation events, or the MutationObserver idea in Boot: Maintain focus within page region when router changes page #86701 (comment) .

¹ A separate point to be made here is that the pages probably shouldn't be asynchronously rendered and that we should optimistically render as much as we can, even if there's still resources that need to be fetched; those can be added to the page after initial rendering, so that we keep the application feeling responsive.

² Not every route is guaranteed to be titled unfortunately, as was the case in the very example that motivated this pull request in the first place. We might want to think about having stronger guarantees or enforcement here, since ideally every route should have a title if it can. #86838 improves this slightly with better documentation at least.

@t-hamano t-hamano left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the detailed explanation!

We merge this more or less as-is, as an improvement over the complete focus loss that happens today

Agreed. I think we can merge this as-is, continue the broader discussion in #77628, and handle the animation case in a follow-up.

This happens after boot renders in response to location change, which happens later after router resolved event is fired.
@aduth
aduth force-pushed the fix/boot-router-focus-loss branch from 79dea85 to acd3efd Compare November 19, 2026 19:10
@aduth
aduth merged commit dee703e into trunk Nov 19, 2026
95 of 96 checks passed
@aduth
aduth deleted the fix/boot-router-focus-loss branch November 19, 2026 20:57
@github-actions github-actions Bot added this to the Gutenberg 24.6 milestone Nov 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

[Focus] Accessibility (a11y) Changes that impact accessibility and need corresponding review (e.g. markup changes). Needs Accessibility Feedback Need input from accessibility [Package] Boot /packages/boot [Type] Bug An existing feature does not function as intended

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Boot: Focus is lost when router replaces stage content

5 participants