Skip to content

Boot: Support targeted focus restoration after navigation - #86979

Open
aduth wants to merge 1 commit into
trunkfrom
add/boot-focus-key
Open

aduth wants to merge 1 commit into
trunkfrom
add/boot-focus-key

Conversation

@aduth

@aduth aduth commented Nov 17, 2026

Copy link
Copy Markdown
Member

What?

Updates @wordpress/boot and @wordpress/admin-ui to coordinate focus restoration after navigation results in the page re-rendering, otherwise resulting in focus loss on the activated link.

This builds upon #86701 , which improves the status quo by focusing the page region as a fallback. This goes further to improve it such that navigation stays on the same effective navigation link element after navigation has completed.

Why?

Focus loss is very disruptive to accessibility and user experience, as the user would have to find their way back to the content to continue from where they left off.

#86701 improved this slightly when a route was re-rendered. But in the case of links, it's more obvious that the focus should stay on the link from which the navigation resulted.

How?

The solution here introduces a data-focus-key attribute that elements within @wordpress/boot can use to assign a unique identifier that is meant to identify an element across navigation transitions. At the time that a navigation is about to occur, @wordpress/boot records if focus is currently within an element with this attribute, and restores focus after navigation completes to the element with matching attribute value after routing is complete.

This is in line with recommendations from spec authors around the Navigation API, which also highlight that this is not something that browsers natively support and requires some custom coordination:

For traversals (i.e. cases where navigateEvent.navigationType === "traverse"), getting parity with the back/forward cache experience requires restoring focus to the same element that was previously focused when that history entry was active. Unfortunately, this isn't something the browser can do automatically for client-side rendered applications; the notion of "the same element" is not generally stable in such cases. So for such cases, using focusReset: "manual", storing some identifier for the currently-focused element in the navigation API state, and calling element.focus() appropriately upon transition could give a better experience

In #86701 (comment), I had mentioned that ideally this would be a situation where the navigation would not be unmounted so that focus could remain on the same element. However, the design of @wordpress/boot and routes are such that each route is responsible for rendering its full content when matched, and rendering <Page /> results in a new element each time.

Testing Instructions

There isn't currently anywhere in the application that uses navigation to demonstrate the fix here. Repeating steps from #86700 will show the effective improvement in #86701 by keeping focus within the page.

Use of AI Tools

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

@aduth
aduth added this pull request to stack #86980 November 17, 2026 20:42
Copilot AI balanced review requested due to automatic review settings November 17, 2026 20:42
@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

🤖 PR meta 🤖

Preview in WordPress Playground Preview in Storybook

🎉 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>

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.

🏷️ Labels

This pull request needs exactly one label indicating its type, and has 0.

  • Required: any label starting with [Type].
  • Found: none.

Read more about Type labels in Gutenberg. If you cannot add labels yourself, a reviewer can do it for you.

📦 Bundle size

Size Change: +198 B (0%)

Total Size: 8.68 MB

📦 View Changed
Filename Size Change
build/modules/boot/index.min.js 51.9 kB +173 B (+0.33%)
build/scripts/edit-site/index.min.js 382 kB +25 B (+0.01%)

e25781e Run

⚡ Performance

Show the results

Client side metrics exclude the server response time.

front-end-block-theme

Metric c6e075a trunk % Change
timeToFirstByte 49.05 ms +5.4% -3.87% 49.8 ms +6.02% -2.81% -1.51%
largestContentfulPaint 80 ms +5% -5% 80 ms +2.5% -5% 0%
lcpMinusTtfb 29 ms +8.28% -6.38% 27.6 ms +7.97% -3.44% 5.07%
wpBeforeTemplate 24.85 ms +8.69% -2.78% 24.75 ms +5.45% -1.7% 0.4%
wpTemplate 19.83 ms +5.14% -2.57% 20.38 ms +4.51% -3.73% -2.7%
wpTotal 44.87 ms +6.37% -3.12% 45.81 ms +3.78% -3.1% -2.05%
wpMemoryUsage 7.75 MB +0% -0% 7.71 MB +0% -0% 0.45%
wpDbQueries 16 +0% -0% 16 +0% -0% 0%

front-end-classic-theme

Metric c6e075a trunk % Change
timeToFirstByte 40.75 ms +4.29% -4.91% 40.35 ms +8.92% -3.22% 0.99%
largestContentfulPaint 76 ms +5.26% -5.26% 76 ms +0% -5.26% 0%
lcpMinusTtfb 34.5 ms +9.71% -4.2% 33.3 ms +7.06% -4.05% 3.6%
wpBeforeTemplate 21.44 ms +4.06% -2.57% 21.45 ms +8.9% -2.52% -0.05%
wpTemplate 15.72 ms +5.47% -8.78% 15.36 ms +4.17% -5.47% 2.34%
wpTotal 37.58 ms +4.2% -5.4% 37.1 ms +8.41% -3.69% 1.29%
wpMemoryUsage 6.44 MB +0% -0% 6.40 MB +0% -0% 0.56%
wpDbQueries 13 +0% -0% 13 +0% -0% 0%

media-processing

Metric c6e075a trunk % Change
mediaProcessingJpeg 393.51 ms +0.26% -0.5% 391.09 ms +0.61% -0.33% 0.62%
mediaProcessingAvif 5767.35 ms +0.14% -0.23% 5766.48 ms +0.13% -0.12% 0.02%
mediaProcessingJpegToAvif 3943.49 ms +0.12% -0.61% 3922.32 ms +0.33% -0.47% 0.54%

media-upload

Metric c6e075a trunk % Change
jpegUploadProcessing 1507.61 ms +33.32% -1.03% 1483.28 ms +1.08% -0.56% 1.64%
pngUploadProcessing 255.13 ms +3.66% -3.73% 258.33 ms +2% -4.84% -1.24%
largeJpegUploadProcessing 1479.88 ms +0.96% -1.01% 1488.91 ms +0.72% -0.9% -0.61%
multipleImageUploadProcessing 1664.62 ms +6.32% -1.9% 1647.96 ms +0.82% -0.46% 1.01%

post-editor

Metric c6e075a trunk % Change
serverResponse 492.55 ms +1.81% -8.08% 450.62 ms +10.93% -0.75% 9.3%
firstPaint 428.67 ms +11.89% -2.25% 431.92 ms +7.54% -6.24% -0.75%
domContentLoaded 850.79 ms +2.06% -2.09% 846.5 ms +2.01% -1.05% 0.51%
loaded 851.76 ms +2.11% -2.05% 847.82 ms +2% -1.06% 0.46%
firstContentfulPaint 490.17 ms +5.13% -3.82% 470.36 ms +3.8% -1.25% 4.21%
firstBlock 2256.08 ms +2.81% -2.68% 2277.47 ms +1.02% -2.12% -0.94%
type 18.36 ms +10.46% -8.93% 19.56 ms +7.16% -5.83% -6.13%
typeWithoutInspector 17.61 ms +7.89% -6.64% 18.31 ms +4.42% -11.03% -3.82%
typeWithTopToolbar 23.95 ms +7.56% -5.22% 25.32 ms +5.96% -9.6% -5.41%
typeContainer 8.57 ms +7.47% -17.74% 8.83 ms +3.74% -12.91% -2.94%
focus 128.38 ms +6% -5.55% 129.17 ms +8.35% -6.92% -0.61%
firstFocus 275.31 ms +0% -0% 290.05 ms +0% -0% -5.08%
selectAll 428.36 ms +0.35% -2.21% 428 ms +1.89% -1.46% 0.08%
undo 30.34 ms +3.59% -4.48% 30.21 ms +6.69% -4.37% 0.43%
listViewOpen 80.12 ms +11.84% -7.01% 81.41 ms +8.06% -9.95% -1.58%
inserterOpen 44.6 ms +12.15% -6.21% 46.26 ms +8.41% -13.47% -3.59%
inserterHover 12.82 ms +5.54% -12.48% 11.66 ms +10.89% -8.49% 9.95%
inserterSearch 8.75 ms +10.51% -10.17% 8.77 ms +20.98% -7.53% -0.23%
loadPatterns 674.62 ms +9% -6% 701.56 ms +3.83% -6.57% -3.84%
wpTotal 482.72 ms +1.85% -8.24% 440.79 ms +11.08% -0.76% 9.51%
wpMemoryUsage 14.81 MB +0% -0% 14.77 MB +0% -0% 0.25%
wpDbQueries 55 +0% -0% 55 +0% -0% 0%

site-editor

Metric c6e075a trunk % Change
serverResponse 257.2 ms +3.34% -5.73% 240.94 ms +3.34% -6.7% 6.75%
firstPaint 319.11 ms +3.69% -13.3% 243.53 ms +24.26% -2.16% 31.04%
domContentLoaded 552.06 ms +4.84% -1.24% 518.11 ms +1.28% -1.28% 6.55%
loaded 552.87 ms +4.84% -1.26% 518.85 ms +1.28% -1.3% 6.56%
firstContentfulPaint 319.11 ms +9.47% -2.15% 291.67 ms +3.75% -1.15% 9.41%
firstBlock 1670.66 ms +1.62% -0.93% 1588.1 ms +1.99% -1.48% 5.2%
type 11.47 ms +13.43% -3.75% 12.71 ms +6.69% -7.47% -9.76%
navigate 87.25 ms +8.95% -12.85% 80.74 ms +3.12% -1.62% 8.06%
loadPatterns 979.65 ms +2.68% -3.25% 949.58 ms +3.15% -10.9% 3.17%
loadPages 914.41 ms +1.6% -2.49% 906.88 ms +3.93% -0.69% 0.83%
wpTotal 250.79 ms +3.4% -6.02% 234.78 ms +3.4% -6.92% 6.82%
wpMemoryUsage 12.82 MB +0% -0% 12.79 MB +0% -0% 0.25%
wpDbQueries 45 +0% -0% 45 +0% -0% 0%

e25781e 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.

As a site builder, I want to insert a core navigation overlay pattern with CTA and see it on the frontend in /test/e2e/specs/site-editor/navigation-overlay-template-part.spec.js, passed after 1 failed attempt.
Error: expect(locator).toBeVisible() failed

Locator:  getByRole('option', { name: /Overlay with site info and CTA/i })
Expected: visible
Received: hidden
Timeout:  5000ms

Call log:
  - Expect "toBeVisible" getByRole('option', { name: /Overlay with site info and CTA/i }) with timeout 5000ms
  - waiting for getByRole('option', { name: /Overlay with site info and CTA/i })
    14 × locator resolved to <div role="option" tabindex="-1" data-base-ui-tooltip-trigger="" aria-label="Overlay with site info and CTA" class="block-editor-block-patterns-list__item" id="core/navigation-overlay-centered-with-extras" aria-describedby="block-editor-block-patterns-list__item-description-4">…</div>
       - unexpected value "hidden"

    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/site-editor/navigation-overlay-template-part.spec.js:254:31
As a user I want to be able to add multiple close buttons so that users can close the overlay from different positions in /test/e2e/specs/site-editor/navigation-overlay-template-part.spec.js, passed after 1 failed attempt.
Error: expect(locator).toHaveCount(expected) failed

Locator:  getByRole('button', { name: 'Close' })
Expected: 2
Received: 1
Timeout:  5000ms

Call log:
  - Expect "toHaveCount" getByRole('button', { name: 'Close' }) with timeout 5000ms
  - waiting for getByRole('button', { name: 'Close' })
    14 × locator resolved to 1 element
       - unexpected value "1"

    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/site-editor/navigation-overlay-template-part.spec.js:228:33
Overlay menu interactions in Safari (@WebKit) in /test/e2e/specs/editor/blocks/navigation-frontend-interactivity.spec.js, passed after 1 failed attempt.
TimeoutError: locator.click: Timeout 10000ms exceeded.
Call log:
  - waiting for getByRole('region', { name: 'Editor top bar' }).getByRole('button', { name: 'Save', exact: true })
    - locator resolved to <button type="button" aria-disabled="true" class="components-button editor-post-publish-button editor-post-publish-button__button is-primary is-compact">Save</button>
  - attempting click action
    2 × waiting for element to be visible, enabled and stable
      - element is not enabled
    - retrying click action
    - waiting 20ms
    2 × waiting for element to be visible, enabled and stable
      - element is not enabled
    - retrying click action
      - waiting 100ms
    16 × waiting for element to be visible, enabled and stable
       - element is not enabled
     - retrying click action
       - waiting 500ms

    at Editor.saveSiteEditorEntities (/home/runner/work/gutenberg/gutenberg/packages/e2e-test-utils-playwright/src/editor/site-editor.ts:39:22)
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/blocks/navigation-frontend-interactivity.spec.js:39:4
persists Copy and Images guidelines across a refresh in /test/e2e/specs/admin/guidelines.spec.js, passed after 1 failed attempt.
Error: expect(locator).toBeVisible() failed

Locator: getByTestId('snackbar').filter({ hasText: 'Guidelines saved.' })
Expected: visible
Timeout: 5000ms
Error: element(s) not found

Call log:
  - Expect "toBeVisible" getByTestId('snackbar').filter({ hasText: 'Guidelines saved.' }) with timeout 5000ms
  - waiting for getByTestId('snackbar').filter({ hasText: 'Guidelines saved.' })

    at saveSectionGuidelines (/home/runner/work/gutenberg/gutenberg/test/e2e/specs/admin/guidelines.spec.js:88:4)
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/admin/guidelines.spec.js:267:3
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
should select synced pattern in /test/e2e/specs/editor/various/writing-flow.spec.js, passed after 1 failed attempt.
Error: expect(locator).toBeFocused() failed

Locator:  locator('[name="editor-canvas"]').contentFrame().locator('[data-type="core/block"]')
Expected: focused
Received: inactive
Timeout:  5000ms

Call log:
  - Expect "toBeFocused" locator('[name="editor-canvas"]').contentFrame().locator('[data-type="core/block"]') with timeout 5000ms
  - waiting for locator('[name="editor-canvas"]').contentFrame().locator('[data-type="core/block"]')
    14 × locator resolved to <div tabindex="0" role="document" draggable="true" data-title="Pattern" data-type="core/block" data-is-drop-zone="true" aria-label="Block: Pattern" id="block-950201a9-1a54-4b06-89c0-4edf40bca7ae" data-block="950201a9-1a54-4b06-89c0-4edf40bca7ae" class="block-editor-block-list__block wp-block is-selected is-reusable block-library-block__reusable-block-container wp-block-block block-editor-block-list__layout">…</div>
       - unexpected value "inactive"

    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/writing-flow.spec.js:1464:5

e25781e Run

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.

🟢 Approval recommended

No active review issues remain for the navigation-focus restoration change.

No open issues 🎉

What changed in this PR

Extends Boot’s page-region focus fallback to restore focus to the equivalent navigation control after a route replaces page content, helping keyboard and screen reader users keep their place.

Changes:

  • Records data-focus-key before navigation and restores focus to a matching element afterward.
  • Adds stable focus keys to Admin UI navigation links.
  • Adds regression tests, shared navigation fixtures, and documentation.
File Description
packages/​boot/​src/​components/​app/​use-route-focus.ts Captures and restores keyed focus across navigation.
packages/​boot/​src/​components/​app/​test/​navigation-focus.browser.test.tsx Tests targeted restoration and controls blurred before navigation.
packages/​boot/​src/​components/​app/​test/​fixtures/​settings.tsx Adds section navigation to the settings fixture.
packages/​boot/​src/​components/​app/​test/​fixtures/​settings-general.tsx Adds section navigation to the general settings fixture.
packages/​boot/​src/​components/​app/​test/​fixtures/​section-navigation.tsx Provides shared navigation items and a router link adapter.
packages/​boot/​README.md Documents focus restoration and fallback behavior.
packages/​boot/​CHANGELOG.md Records targeted focus restoration.
packages/​admin-ui/​src/​navigation/​test/​index.jsdom.test.tsx Verifies navigation links receive href-based focus keys.
packages/​admin-ui/​src/​navigation/​index.tsx Adds stable focus keys to navigation links.
packages/​admin-ui/​CHANGELOG.md Records section-navigation focus support.

Review effort: Balanced

Base automatically changed from fix/boot-router-focus-loss to trunk November 19, 2026 20:57
@aduth
aduth force-pushed the add/boot-focus-key branch from 17fb731 to e25781e Compare November 19, 2026 21:00

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

[Package] Admin UI /packages/admin-ui [Package] Boot /packages/boot

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants