Skip to content

Navigation: Add a Tablet overlay visibility option - #87002

Draft
getdave wants to merge 16 commits into
add/viewport-media-queries-desktopfrom
add/navigation-overlay-tablet
Draft

getdave wants to merge 16 commits into
add/viewport-media-queries-desktopfrom
add/navigation-overlay-tablet

Conversation

@getdave

@getdave getdave commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

What?

Adds a Tablet option to the Navigation block's Overlay Visibility control. With Tablet selected, the menu collapses into the overlay at the theme's tablet breakpoint and below, and shows its links inline above it. The breakpoint comes from settings.viewport.tablet in theme.json, which is the same value the editor's Tablet preview and Responsive styles use.

Why?

Controlling when the Navigation block collapses has been one of the longest-running requests for the block. #45274 tried a free-form pixel breakpoint per block. In review, talldan pointed out that this would give the Navigation block a third breakpoint of its own, separate from the viewport breakpoints that themes can now set in theme.json (#79104), and one you can't preview precisely in the editor. They suggested starting with a Tablet value that follows the theme's breakpoints, which is what this PR does.

Following the theme's breakpoints means:

  • themes control the actual width in one place, through theme.json;
  • the editor's Tablet and Mobile previews show exactly what visitors will see;
  • nothing a user types ends up in a CSS media query.

How?

  • One resolver for every decision. getOverlayViewports() (JS) and block_core_navigation_get_overlay_viewports() (PHP) turn overlayMenu into a map of the viewports where the overlay shows. Responsive markup, the always-shown state, the generated CSS and the overlay template part preview all read from that map. PR 3 adds a filter around it.
  • Front end. Blocks set to Tablet get rules that show the links inline in each viewport where the overlay is off, inside the media queries from get_viewport_media_queries(). The class that scopes them is a hash of the rules, so identical blocks share one class and the rules print once.
  • Static 600px rules. Tablet blocks opt out of the existing 600px rules through a has-overlay-viewports class. The opt-out uses :where(), so the default rules keep exactly the specificity they had before, and theme CSS that overrides the breakpoint today keeps working.
  • Editor. The same rules are injected into the canvas with useStyleOverride. They're CSS media queries, so in the iframed canvas the device previews and resizing behave like the front end. If the canvas isn't iframed, they follow the browser window, as other responsive styles do.
  • Inspector. The Tablet option only appears when the theme has a tablet breakpoint, the same condition the editor uses for its Tablet preview. A saved Tablet value stays visible either way.
  • Overlay template parts. Editing a Tablet block's overlay opens the template part in the Tablet preview, the widest width where the overlay shows.

Known issue: the Mobile label

The existing Mobile option collapses below a fixed 600px. The editor's Mobile viewport is 480px by default, so "Mobile" now means two different widths depending on where you look. This PR deliberately leaves Mobile as it is so existing sites don't change, but we need to decide how to resolve it. Ideas welcome.

Compatibility

  • A block saved with Tablet on a version without this PR behaves like Mobile, because older versions treat anything other than Off as responsive.
  • If a theme only configures a mobile breakpoint, Tablet collapses at that breakpoint and the Tablet option is hidden.
  • On those older versions, the Overlay Visibility control also shows no option selected for a saved Tablet value.
  • From the post editor, overlay template parts open at desktop width for both Mobile and Tablet, because the post editor ignores the viewport parameter. That gap already exists on trunk.

For theme authors

Tablet blocks get two new classes on the nav element, has-overlay-viewports and a hashed wp-navigation-overlay-* class that scopes the generated rules. Those rules are deliberately more specific than the static 600px ones. CSS that overrides the breakpoint today keeps working for blocks set to Mobile, but it won't affect blocks set to Tablet, which follow settings.viewport instead.

Dev note

This PR and PR 3 share a dev note, drafted alongside PR 3, because the Tablet option and the multilingual filter need explaining together.

Testing Instructions

  1. Add a Navigation block with a few links to a post.
  2. In the block's Overlay settings, set Overlay Visibility to Tablet.
  3. Switch the editor preview to Tablet. The menu should show the open button. Switch to Desktop and the links should show inline.
  4. Publish and view the post. Resize the window across 782px and check the menu switches at that width.
  5. Add "settings": { "viewport": { "mobile": "480px", "tablet": "60em" } } to your theme's theme.json and check the switch moves to 960px, in both the editor and the front end. Set both values, because a theme that sets only one loses the other default.
  6. With that setting, add a submenu to the Navigation block and open the overlay at about 850px wide. Submenus should still open in the overlay as they do on a narrow screen, with left and right justification and with a custom overlay.
  7. Check a block set to Mobile still switches at 600px.

Automated tests:

  • npm run test:unit -- packages/block-library/src/navigation
  • npm run test:unit:php:base -- --filter Render_Block_Navigation_Test
  • npm run test:e2e -- test/e2e/specs/editor/blocks/navigation-overlay-viewports.spec.ts

Use of AI Tools

Written with Claude Code (Claude Opus 5.5) and opened as a draft. I still need to review it myself before it's ready for review.

🤖 Generated with Claude Code

@getdave getdave added [Type] Enhancement A suggestion for improvement. [Block] Navigation Affects the Navigation Block Needs Dev Note Requires a developer note for a major WordPress release cycle labels Nov 18, 2026
@github-actions github-actions Bot added the [Package] Block library /packages/block-library label Nov 18, 2026
@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

🤖 PR meta 🤖

Preview in WordPress Playground Preview in Storybook

📦 Bundle size

Size Change: +1.01 kB (+0.01%)

Total Size: 8.66 MB

📦 View Changed
Filename Size Change
build/scripts/block-library/index.min.js 427 kB +864 B (+0.2%)
build/styles/block-library/navigation/style-rtl.css 3.8 kB +16 B (+0.42%)
build/styles/block-library/navigation/style-rtl.min.css 2.61 kB +16 B (+0.62%)
build/styles/block-library/navigation/style.css 3.8 kB +17 B (+0.45%)
build/styles/block-library/navigation/style.min.css 2.6 kB +17 B (+0.66%)
build/styles/block-library/style-rtl.css 22.9 kB +21 B (+0.09%)
build/styles/block-library/style-rtl.min.css 19.4 kB +18 B (+0.09%)
build/styles/block-library/style.css 23 kB +21 B (+0.09%)
build/styles/block-library/style.min.css 19.4 kB +17 B (+0.09%)

22f82e8 Run

⚡ Performance

Show the results

Client side metrics exclude the server response time.

front-end-block-theme

Metric 997b756 add/viewport-media-queries-desktop % Change
timeToFirstByte 44.6 ms +9.64% -2.47% 46.7 ms +9.96% -3.53% -4.5%
largestContentfulPaint 76 ms +2.63% -5.26% 74 ms +8.11% -8.11% 2.7%
lcpMinusTtfb 30.3 ms +5.94% -18.48% 24.75 ms +28.08% -7.47% 22.42%
wpBeforeTemplate 22.92 ms +11.17% -3.4% 23.84 ms +9.23% -4.07% -3.86%
wpTemplate 18.07 ms +3.27% -5.48% 19.22 ms +5.25% -6.82% -5.98%
wpTotal 41.27 ms +9.98% -3% 43.05 ms +11.06% -3.72% -4.13%
wpMemoryUsage 7.75 MB +0% -0% 7.74 MB +0% -0% 0.05%
wpDbQueries 16 +0% -0% 16 +0% -0% 0%

front-end-classic-theme

Metric 997b756 add/viewport-media-queries-desktop % Change
timeToFirstByte 36.35 ms +7.02% -3.3% 39.4 ms +5.58% -4.44% -7.74%
largestContentfulPaint 68 ms +0% -5.88% 70 ms +2.86% -2.86% -2.86%
lcpMinusTtfb 29.5 ms +7.63% -2.2% 30.3 ms +3.8% -5.61% -2.64%
wpBeforeTemplate 19.76 ms +4.86% -1.87% 20.99 ms +6.81% -3.29% -5.86%
wpTemplate 13.51 ms +7.7% -4.15% 14.83 ms +7.42% -6.74% -8.9%
wpTotal 33.63 ms +6.48% -3.27% 36.23 ms +6.29% -4.25% -7.18%
wpMemoryUsage 6.44 MB +0% -0% 6.43 MB +0% -0% 0.06%
wpDbQueries 13 +0% -0% 13 +0% -0% 0%

media-processing

Metric 997b756 add/viewport-media-queries-desktop % Change
mediaProcessingJpeg 332.71 ms +0.23% -1.42% 332.72 ms +5.07% -0.72% 0%
mediaProcessingAvif 4867.25 ms +0.3% -0.12% 4885.85 ms +0.07% -0.25% -0.38%
mediaProcessingJpegToAvif 3406.59 ms +0.51% -0.15% 3420.38 ms +0.2% -0.11% -0.4%

media-upload

Metric 997b756 add/viewport-media-queries-desktop % Change
jpegUploadProcessing 1476.76 ms +1.32% -1.01% 1465.18 ms +0.32% -1.06% 0.79%
pngUploadProcessing 254.83 ms +12.98% -3.72% 256.62 ms +10.37% -5.4% -0.7%
largeJpegUploadProcessing 1462.31 ms +0.79% -0.47% 1449.26 ms +0.96% -1.46% 0.9%
multipleImageUploadProcessing 1594.17 ms +8.74% -1.13% 1549.11 ms +1.57% -1.53% 2.91%

post-editor

Metric 997b756 add/viewport-media-queries-desktop % Change
serverResponse 331.35 ms +2.74% -9.81% 327.41 ms +1.26% -11.17% 1.2%
firstPaint 331.46 ms +15.32% -1.45% 345.79 ms +3.85% -12.18% -4.14%
domContentLoaded 665.54 ms +10.08% -1.97% 638.26 ms +2.22% -0.72% 4.27%
loaded 666.41 ms +10.07% -1.97% 639.13 ms +2.22% -0.72% 4.27%
firstContentfulPaint 381.41 ms +16.96% -2.28% 363.39 ms +1.58% -1.18% 4.96%
firstBlock 1780.06 ms +2.17% -2.27% 1709.63 ms +0.15% -0.9% 4.12%
type 15.16 ms +7.72% -7.65% 16.02 ms +3.56% -5.12% -5.37%
typeWithoutInspector 16.29 ms +1.1% -12.34% 14.5 ms +6.76% -6.48% 12.34%
typeWithTopToolbar 21.7 ms +12.95% -11.01% 18.94 ms +7.5% -2.53% 14.57%
typeContainer 7.27 ms +3.16% -6.33% 6.49 ms +15.41% -10.79% 12.02%
focus 96.62 ms +5.45% -2.8% 98.81 ms +3.57% -6.65% -2.22%
firstFocus 221.18 ms +0% -0% 213.72 ms +0% -0% 3.49%
selectAll 322.78 ms +2.22% -3.22% 308.4 ms +2.68% -0.67% 4.66%
undo 24.74 ms +4.89% -3.52% 24.04 ms +7.24% -4.49% 2.91%
listViewOpen 63.67 ms +4.04% -5.8% 59.1 ms +9.98% -10.66% 7.73%
inserterOpen 35.87 ms +18.57% -5.21% 33.67 ms +6.03% -6.36% 6.53%
inserterHover 10.08 ms +5.75% -9.62% 9.24 ms +8.55% -6.82% 9.09%
inserterSearch 6.9 ms +1.88% -3.04% 7 ms +6.29% -6% -1.43%
loadPatterns 522.23 ms +4.33% -4% 512.53 ms +4.52% -1.64% 1.89%
wpTotal 322.64 ms +2.81% -10.08% 318.67 ms +1.28% -11.41% 1.25%
wpMemoryUsage 14.81 MB +0% -0% 14.80 MB +0% -0% 0.02%
wpDbQueries 55 +0% -0% 55 +0% -0% 0%

site-editor

Metric 997b756 add/viewport-media-queries-desktop % Change
serverResponse 322.95 ms +0.6% -9.33% 311.37 ms +1.24% -8.77% 3.72%
firstPaint 392.42 ms +6.52% -16.98% 337.53 ms +11.5% -10.93% 16.26%
domContentLoaded 688.72 ms +1.69% -2.39% 645.1 ms +1.84% -1.54% 6.76%
loaded 689.56 ms +1.7% -2.38% 645.85 ms +1.83% -1.55% 6.77%
firstContentfulPaint 403.12 ms +3.7% -6.46% 366.12 ms +2.79% -1.35% 10.11%
firstBlock 2069.65 ms +6.29% -2.03% 1965.61 ms +0.41% -0.34% 5.29%
type 13.86 ms +10.32% -6.71% 14.93 ms +4.15% -6.43% -7.17%
navigate 88.22 ms +4.05% -7.61% 100.85 ms +0.08% -3.74% -12.52%
loadPatterns 971.58 ms +11.06% -8.52% 1207.9 ms +5.62% -10.91% -19.56%
loadPages 978.14 ms +2.42% -0.49% 978.42 ms +4.16% -5.39% -0.03%
wpTotal 314.63 ms +0.6% -9.63% 303.18 ms +1.24% -9.06% 3.78%
wpMemoryUsage 12.82 MB +0% -0% 12.82 MB +0% -0% 0.02%
wpDbQueries 45 +0% -0% 45 +0% -0% 0%

22f82e8 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.

Navigates the list via UP/DOWN arrow keys from action buttons in /test/e2e/specs/site-editor/dataviews-list-layout-keyboard.spec.js, passed after 1 failed attempt.
Error: expect(locator).toBeFocused() failed

Locator:  getByRole('row', { name: 'Page Two Edit Actions' }).getByRole('button', { name: 'Edit' })
Expected: focused
Received: inactive
Timeout:  5000ms

Call log:
  - Expect "toBeFocused" getByRole('row', { name: 'Page Two Edit Actions' }).getByRole('button', { name: 'Edit' }) with timeout 5000ms
  - waiting for getByRole('row', { name: 'Page Two Edit Actions' }).getByRole('button', { name: 'Edit' })
    14 × locator resolved to <button type="button" tabindex="-1" class="components-button is-small" id="view-list-0-170-primary-action-edit-post">Edit</button>
       - unexpected value "inactive"

    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/site-editor/dataviews-list-layout-keyboard.spec.js:243:5
Undo restores the post selection when another synced entity is loaded in /test/e2e/specs/editor/collaboration/collaboration-undo-redo.spec.ts, passed after 1 failed attempt.
Error: expect(received).toMatchObject(expected)

- Expected  - 2
+ Received  + 2

  Object {
    "attributeKey": "content",
    "blockIndex": 0,
    "content": "abcdef",
-   "endOffset": 3,
-   "offset": 3,
+   "endOffset": 2,
+   "offset": 2,
  }

Call Log:
- Timeout 5000ms exceeded while waiting on the predicate
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/collaboration/collaboration-undo-redo.spec.ts:363:5
should apply a named font size using the font size buttons in /test/e2e/specs/editor/various/font-size-picker.spec.js, passed after 1 failed attempt.
Error: expect(received).toBe(expected) // Object.is equality

- Expected  - 2
+ Received  + 2

- <!-- wp:paragraph {"fontSize":"large"} -->
+ <!-- wp:paragraph {"fontSize":"medium"} -->
- <p class="has-large-font-size">Paragraph to be made "large"</p>
+ <p class="has-medium-font-size">Paragraph to be made "large"</p>
  <!-- /wp:paragraph -->

Call Log:
- Timeout 5000ms exceeded while waiting on the predicate
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/font-size-picker.spec.js:153:6
should reset a named font size using the tools panel menu in /test/e2e/specs/editor/various/font-size-picker.spec.js, passed after 1 failed attempt.
Error: expect(received).toBe(expected) // Object.is equality

- Expected  - 2
+ Received  + 2

- <!-- wp:paragraph {"fontSize":"medium"} -->
+ <!-- wp:paragraph {"fontSize":"small"} -->
- <p class="has-medium-font-size">Paragraph with font size reset using tools panel menu</p>
+ <p class="has-small-font-size">Paragraph with font size reset using tools panel menu</p>
  <!-- /wp:paragraph -->

Call Log:
- Timeout 5000ms exceeded while waiting on the predicate
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/font-size-picker.spec.js:178: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-dccac746-548b-4220-8386-767f4d078998" data-block="dccac746-548b-4220-8386-767f4d078998" 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

22f82e8 Run

getdave and others added 16 commits November 18, 2026 08:39
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@getdave
getdave force-pushed the add/navigation-overlay-tablet branch from 4f16610 to 22f82e8 Compare November 18, 2026 08:40
@getdave
getdave added this pull request to stack #87004 November 18, 2026 08:57

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

[Block] Navigation Affects the Navigation Block Needs Dev Note Requires a developer note for a major WordPress release cycle [Package] Block library /packages/block-library [Type] Enhancement A suggestion for improvement.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant