WordPress 7.0 introduces Customisable Navigation Overlays, giving site owners full control over their mobile navigation menus using the block Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. editor.
Previously, when a visitor tapped a hamburger menu icon on a mobile device, WordPress displayed a fixed default overlay with no support for customisation. The design, layout, and content were locked.
Customisable Navigation Overlays remove this restriction entirely — any overlay can now be built from blocks and patterns in the Site Editor. This includes a dedicated Navigation Overlay Close block for placing and styling a close button anywhere within the overlay.
How overlays work
Navigation overlays are implemented as template parts using a new navigation-overlay template part area, managed principally through the Navigation block’s overlay controls in the Site Editor. Because they are template parts, they can also be found and edited via the Patterns section in the Site Editor sidebar A sidebar in WordPress is referred to a widget-ready area used by WordPress themes to display information that is not a part of the main content. It is not always a vertical column on the side. It can be a horizontal rectangle below or above the content area, footer, header, or any where in the theme.. Each overlay is assigned to a Navigation block — while the same overlay can be referenced by more than one, a one-to-one relationship is the most common pattern.
What goes inside an overlay is entirely up to the author. As a standard block canvas, it can contain any block — navigation, social icons, a search field, a site logo, calls to action…or any combination! A Navigation block is the typical inclusion but is not a requirement. Because overlays only function correctly when rendered by a Navigation block, overlay template parts are intentionally excluded from the general block inserter — this prevents them from being inserted accidentally into other parts of a template.
The feature is opt-in: by default, the Navigation block continues to use the standard overlay behaviour from previous versions of WordPress. A custom overlay can be activated in three ways:
- Creating a new overlay — via the Overlays section in the Navigation block’s sidebar controls in the Site Editor
- Selecting an existing overlay — from the same controls, choosing from any overlays already created or bundled with the active theme
- Theme pre-assignment — a theme can reference a bundled overlay directly in the Navigation block markup (covered in the developer section below)
For theme developers: bundling overlays with your theme
Themes can ship pre-built navigation overlays so they are available as soon as the theme is activated. The recommended approach is to provide both a default overlay template part and a set of overlay patterns.
Template parts vs patterns
Understanding the distinction helps decide how to structure an overlay offering:
- A template part is the overlay itself — the component that gets rendered when a Navigation block uses an overlay. Shipping a template part means a ready-to-use overlay is available from the moment the theme is activated.
- Patterns are design options that appear in the Design tab when editing a navigation overlay in the Site Editor. Selecting a pattern replaces the current overlay content with the pattern’s block markup, letting users switch between distinct designs.
A patterns-only approach is also valid — useful when a theme wants to offer design options without pre-applying an overlay automatically. In this case, users create a new overlay via the Navigation block’s controls and pick from the theme’s patterns as a starting point.
Updating your Theme
1. Register the template part in theme.json
Registering the template part in theme.json is required. Without it, the template part is assigned the uncategorized area and will not be recognised by the Navigation block as an overlay.
Add an entry to the templateParts array, setting area to navigation-overlay:
{
"templateParts": [
{
"area": "navigation-overlay",
"name": "my-custom-overlay",
"title": "My Custom Overlay"
}
]
}
2. Create the template part file
Create the corresponding HTML HyperText Markup Language. The semantic scripting language primarily used for outputting content in web browsers. file in the theme’s parts/ directory. The filename should match the name value from theme.json.
It is strongly recommended to include the Navigation Overlay Close block within the overlay. If it is omitted, WordPress will automatically insert a fallback close button on the frontend for accessibility Accessibility (commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology (for example, computer screen readers). (https://en.wikipedia.org/wiki/Accessibility) and usability reasons — but that button may not match the overlay’s design or be positioned as expected. Including it explicitly gives full control over its appearance and placement.
<!-- parts/my-custom-overlay.html -->
<!-- wp:group {"layout":{"type":"flex","orientation":"vertical"}} -->
<div class="wp-block-group">
<!-- wp:navigation-overlay-close /-->
<!-- wp:navigation {"layout":{"type":"flex","orientation":"vertical"}} /-->
</div>
<!-- /wp:group -->
3. Register overlay patterns
Overlay patterns are registered using register_block_pattern(). Setting blockTypes to core/template-part/navigation-overlay scopes the pattern so it only appears when editing a navigation overlay template part — not in the general inserter.
register_block_pattern(
'my-theme/navigation-overlay-default',
array(
'title' => __( 'Default Overlay', 'my-theme' ),
'categories' => array( 'navigation' ),
'blockTypes' => array( 'core/template-part/navigation-overlay' ),
'content' => '<!-- wp:group {"layout":{"type":"flex","orientation":"vertical"}} -->
<div class="wp-block-group">
<!-- wp:navigation-overlay-close /-->
<!-- wp:navigation {"layout":{"type":"flex","orientation":"vertical"}} /-->
</div>
<!-- /wp:group -->',
)
);
4. Pre-configuring the Navigation block (optional)
A theme can optionally pre-configure a Navigation block to reference a specific overlay by setting the overlay attribute in the block markup. The value should be the template part slug only — without a theme prefix:
<!-- wp:navigation {"overlay":"my-custom-overlay"} /-->
Using the slug only — without a theme prefix — is important for future compatibility: WordPress plans to allow template parts to persist across theme switches, and a theme-prefixed identifier would break that. This follows the same convention as header and footer template parts.
The overlay attribute is entirely optional — users can select or change the overlay at any time using the Navigation block’s sidebar controls.
Known limitations
Template parts and theme switching
Navigation overlay template parts are currently tied to the active theme. Custom overlays will not be preserved if the active theme is switched. This is a known limitation tracked in gutenberg#72452.
Overlays are full-screen only
In this initial release, navigation overlays are always rendered full-screen. Non-full-screen overlay styles (such as a sidebar drawer) are not yet supported. This requires implementing overlays as a true <dialog> element — including support for clicking outside to close — which is planned for a future release.
Not a generic popup or dialog
Navigation Overlays are intentionally scoped to the Navigation block and are not designed as a general-purpose popup or dialog implementation. For broader use cases — such as modal dialogs triggered by arbitrary content — a dedicated Dialog block is in development and tracked in gutenberg#61297.
Questions and feedback
Until now, the mobile navigation overlay has been one of the few remaining areas of a block theme that couldn’t be designed in the Site Editor. Navigation Overlays change that. An overlay can contain anything blocks can express — a simple menu with a styled close button, a full-screen layout with the site logo and a call to action, or a content-rich experience that turns the mobile menu into a destination in its own right.
There is a lot of creative space here, and seeing what the community builds with it will be exciting.
Questions are welcome in the comments below.
Further reading
Props @onemaggie for implementation contributions and technical review, @mikachan, @jeryj @scruffian for proofreading, and @mmcalister, whose Ollie Menu Designer plugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party. helped validate community demand for this functionality.
#7-0, #dev-notes, #navigation
You must be logged in to post a comment.