How to Build a Custom Mobile Menu Overlay in WordPress 7.0

The navigation block overlay has never been directly customizable in the editor. But as of WordPress 7.0 you’ll have more options to edit the overlay than ever before. Here’s how to register a custom navigation-overlay template part, wire it up to the Navigation block, and handle the accessibility work WordPress doesn’t do for you.

If you’ve ever tried to build a client site that needed a custom mobile menu in WordPress 6.x, you know how painful it was. The Navigation block’s mobile overlay was hardcoded. You got a fixed full-screen panel, a fixed breakpoint around 600px, and the exact same links your desktop nav showed. If a client asked for a branded background, a menu with social icons and a search field, or anything other than a stacked list of links, you forked CSS, wrote custom JS, or gave up.

WordPress 7.0 finally opens this up. The mobile overlay is now a template part, which means any blocks, any patterns, and full Site Editor access for the people who own the site. In this post, we’ll register a custom overlay, wire it up to the Navigation block, and walk through the accessibility work WordPress gives you for free (and the one piece it doesn’t).

The problem with the old mobile overlay

The 6.x Navigation block offered three overlay options: “always,” “never,” or “mobile” (which used the hardcoded breakpoint). That was the extent of the customization. The actual overlay markup lived in core, you couldn’t change what it contained, and you couldn’t swap it out for different Navigation blocks.

The workaround most of us landed on was CSS-only styling combined with some duplicated markup for the mobile menu. It worked, but it was fragile. Now, with these new overlays, you’ll have way more control over the contents of the overlay.

What’s new in WordPress 7.0

In WordPress 7.0, the mobile overlay is a standard template part. That unlocks a few things:

The overlay is a normal block canvas. You can drop in any block or pattern you want.
Site owners can edit it in the Site Editor without touching code.
Theme authors can ship overlays as part of the theme, the same way they ship headers and footers.
Themes that don’t register anything keep working. WordPress falls back to the old hardcoded overlay if nothing is registered.

One thing worth flagging before we go further: overlays are still full-screen only in 7.0. If a client wants a slide-in drawer, that’s CSS on top of the overlay, not a framework feature yet. The dev note mentions non-full-screen overlays (backed by the native <dialog> element) are planned for a future release, but they aren’t in this one.

Creating an Overlay

Creating an overlay is just like creating other template parts. You can create these either via the Site Editor UI or by creating a template part file yourself and manually registering it in theme.json.

Registering the overlay via the Site Editor

Open the editor and go to Patterns. Then click Add Pattern in the top right corner. Select Add Template Part from the popover that appears. Once you click this, you’ll need to choose the type of template part you want to create (Navigation Overlay) and enter a title before you click create.

Screenshot of the site editor UI for adding a template part. An emphasis box is added around the Navigation Overlay template type.

Once you create the template part, the sidebar will have a number of patterns available for you to start with, or you can add any blocks you want. However, you need to make sure you add things like the navigation (which ideally should be the same one already in use) as well as a close button (more on this later).

Registering the overlay in theme.json

This is the mechanical core of the whole setup. You register a new template part in theme.json under templateParts:

theme.json

JSON

{
  "version": 3,
  "templateParts": [
    {
      "area": "navigation-overlay",
      "name": "primary-overlay",
      "title": "Primary Mobile Overlay"
    }
  ]
}

{
  "version": 3,
  "templateParts": [
    {
      "area": "navigation-overlay",
      "name": "primary-overlay",
      "title": "Primary Mobile Overlay"
    }
  ]
}

A few things to call out here:

The area value must be exactly "navigation-overlay". Anything else and the Navigation block won’t see it. This is the kind of thing that costs you twenty minutes of “why isn’t this working” if you get it wrong.
The name becomes the filename. With the example above, your template part file lives at parts/primary-overlay.html.
The title is the human-readable label that shows up in the editor UI.

Like other template parts, you can have more than one of these so different navigation blocks can use different overlays.

Building the overlay template part

Now you need the actual template part file. Here’s the minimum viable version:

parts/primary-overlay.html

HTML

<!-- wp:group {"layout":{"type":"flex","orientation":"vertical","justifyContent":"center"}} -->
<div class="wp-block-group">
  <!-- wp:navigation {"overlayMenu":"never"} /-->
  <!-- wp:navigation-overlay-close /-->
</div>
<!-- /wp:group -->

<!-- wp:group {"layout":{"type":"flex","orientation":"vertical","justifyContent":"center"}} -->
<div class="wp-block-group">
  <!-- wp:navigation {"overlayMenu":"never"} /-->
  <!-- wp:navigation-overlay-close /-->
</div>
<!-- /wp:group -->

Three things going on in there:

A Group block acts as the overlay’s layout container.
A nested Navigation block with overlayMenu: "never" so it just renders its menu items without a nested overlay (we’re already inside one).
The new core/navigation-overlay-close block handles the close button.

In practice you’re going to want more than that. A realistic overlay for a client site might look something like this: a Site Logo at the top, a Navigation block in the middle, a Search block below that, Social Icons at the bottom, and the close button in the corner.

As noted above, you can create patterns for your own overlays or use the ones that come with WordPress. Even if you make the overlay files yourself, you can hop in the editor and add a pattern or any other blocks you like, just like other template parts.

Make sure to include your own close block

WordPress will insert a fallback close button if you leave one out, but that fallback gets default styling and default placement. If you want the close icon to match the rest of your theme (color, size, position, using icon or text, etc.), drop in core/navigation-overlay-close yourself.

Wiring the Navigation block to the overlay

Registering and building the overlay doesn’t do anything on its own. You still have to tell the Navigation block which overlay to use. To do so, you can set it in your header template part’s Navigation block markup:

HTML

<!-- wp:navigation {"overlayMenu":"always","overlay":"primary-overlay"} /-->

<!-- wp:navigation {"overlayMenu":"always","overlay":"primary-overlay"} /-->

Two attributes do the work here. overlayMenu controls when the overlay is used ("always", "never", or "mobile"). The overlay attribute takes the template part name you registered in theme.json.

Alternatively, you can select the Navigation block in the editor and choose the overlay the block should use. It also shows you a preview of the overlay, which is a nice touch.

Screenshot of the navigation block sidebar settings for the overlay template

Use the slug only, not the theme-prefixed identifier

This one is worth pulling out because it’s easy to get wrong. The overlay attribute takes the template part slug only: "primary-overlay", not "twentytwentysix//primary-overlay". Even though you’re used to seeing template parts referenced with a theme prefix elsewhere, you drop it here.

The reasoning (directly from the dev note) is that WordPress plans to let template parts persist across theme switches in a future release. A theme-prefixed identifier would break that. Same convention as header and footer template parts, for the same reason.

The built-in overlay patterns

WordPress 7.0 ships three starter patterns (Centered, Accent Background, and Dark Background) that show up when a site owner creates a new overlay. Worth mentioning so your clients aren’t staring at a blank canvas on day one.

Agency themes can extend the idea by registering their own patterns targeting "navigation-overlay". That’s a nice hook for shipping branded starting points alongside your theme without locking the client into a single layout.

Accessibility: what WordPress gives you, what you still own

Here’s the good news up front: WordPress 7.0 handles most of the overlay a11y basics out of the box. That hasn’t always been the case with new features, so it’s worth naming.

What’s there

Renders the overlay as <div role="dialog"> with aria-modal="true".
Provides the navigation-overlay-close block with the correct semantics.
Falls back to an auto-inserted close button if the theme forgets one.
Traps focus inside the overlay. Tab and Shift+Tab cycle within the dialog while it’s open.
Closes the overlay on the Escape key.
Returns focus to the hamburger button after the overlay closes.

What’s missing

Screen-reader announcements. In my tests, VoiceOver was unable to announce when the menu opened or closed.

This is pretty great accessibility support for a v1 feature. The dev note indicates there are much more robust overlay features in the works including a dedicated dialog block.

Some helpful facts to know

A handful of real things you’ll hit building for this feature. Some are by-design and will stay. Others are known bugs at release that will likely get patched in point releases. I’ve split them out so the post ages gracefully.

(Probably) intentional quirks

The area value must be exactly "navigation-overlay". Typos fail silently. You’ll just see the old hardcoded overlay and wonder why.
The overlay attribute takes the slug only, no theme prefix. See the earlier section.
Custom overlays created by users through the Site Editor live in the database and don’t travel when the user switches themes unless you save the changes to the theme using Create Block Theme or a similar mechanism.
Overlays are full-screen only in 7.0. If a client wants a slide-in drawer, that’s your CSS on top of the overlay, not a framework option. Non-full-screen overlays using the native <dialog> element are planned for a future release.
Multisite: standard template-part rules apply. Per-site overlays, not network-wide.

Known issues at release (expect point-release fixes)

contentOnly mode hides the overlay panel. The simplified Navigation editing experience shipping as default in 7.0 doesn’t expose the Overlay controls in its sidebar. If you’ve pre-configured an overlay via the overlay attribute and the site owner edits the block in contentOnly mode, they have no UI to swap or edit it. Tracked in gutenberg#75277. Workaround: edit in the full Site Editor.
The default overlay expands all submenus on the front end. Regardless of the Submenu Visibility setting (Hover or Click), the default overlay template renders every submenu expanded. If your theme ships a custom overlay, this doesn’t affect you. If you’re relying on the default, test before shipping. Tracked in gutenberg#76887.
Submenu overflow with right-justified navigation. If your Navigation block uses items-justified-right, a descendant CSS rule cascades into the overlay’s inner nav and pushes submenu items off the left edge of narrow viewports. Easy to miss because it only shows on mobile. Tracked in gutenberg#76360, with a fix PR open at the time of writing.

What I learned

Registering the overlay is the boring part. The interesting work is in the content and the pattern choices. Once the plumbing is in place, you spend your time in the Site Editor like you would on any other template part.
A close block is always included. While you absolutely should include one yourself, I think it’s nice to ensure there’s a baseline of quality a11y support.
The a11y story is better than I expected. Focus trap, Escape to close, return focus on close, and correct ARIA semantics are all included in the initial version, with more improvements to come.
The Navigation block is starting to feel more viable. Historically I haven’t used it because it was super limited and there was no way to customize the overlay without hacks. This feature is a welcome improvement and it’s only the minimum viable product.

One disappointment is that we still can’t customize the breakpoint at which the overlay applies. This is something that I hope will be addressed in a future release so we don’t have to do those CSS hacks anymore. But this is a step in the right direction.