The Navigation block is the cornerstone of site structure in WordPress Full Site Editing. It replaces the classic menu system (Appearance → Menus) with a block-based approach that gives you visual control over menu structure, dropdown behavior, mobile responsiveness, and styling — all within the Site Editor. For theme developers building block themes, understanding the Navigation block at a deep level is essential because your users will interact with it constantly, and your theme needs to provide sensible defaults while allowing full customization. This guide covers everything from basic setup to advanced patterns including mega menus, conditional navigation, accessibility, and performance optimization.
How the Navigation Block Works Under the Hood
The Navigation block stores menu data as a wp_navigation post type in the WordPress database. Each navigation menu is a post containing block markup — Page Link blocks, Custom Link blocks, Submenu blocks, and other inner blocks arranged in a hierarchy. This is fundamentally different from classic menus, which stored menu items as nav_menu_item posts linked to a taxonomy.
The architectural shift matters for theme developers because navigation is no longer registered in PHP with register_nav_menus. Instead, you include a Navigation block in your header template part (parts/header.html), and users configure it through the Site Editor. The block supports a ref attribute that links to a specific wp_navigation post, allowing multiple templates to share the same navigation menu.
When WordPress renders the Navigation block on the front end, it generates semantic HTML with a nav element, proper ARIA attributes, and responsive behavior based on the block’s settings. The generated markup follows accessibility best practices by default — something that classic menu walkers often failed to achieve without custom code.
Setting Up Navigation in Block Theme Templates
In your header template part (parts/header.html), the Navigation block is included as block markup:
The block markup includes the ref attribute pointing to a wp_navigation post ID. When a user first activates your theme, WordPress either uses an existing navigation or creates a new one based on the site’s published pages. You can also ship a default navigation as part of your theme’s starter content.
Navigation Block Attributes for Theme Developers
Understanding the block attributes available helps you set sensible defaults in your templates:
- ref: Links to a wp_navigation post ID. If omitted, the block creates an inline menu.
- overlayMenu: Controls when the mobile menu appears. Values: “never”, “mobile”, “always”. For most themes, “mobile” is the correct default.
- hasIcon: Whether the mobile toggle shows a hamburger icon (true) or text label (false).
- icon: The icon style for the mobile toggle — “handle” (three lines) or “menu” (three lines with different proportions).
- layout: Flex layout settings including orientation (horizontal/vertical) and justification.
- style: Inline style overrides for spacing, typography, and colors.
- textColor and backgroundColor: Preset color slugs from theme.json for menu item colors.
- overlayBackgroundColor and overlayTextColor: Colors for the mobile overlay menu.
Building Dropdown Submenus
Dropdown menus in the Navigation block use the Submenu block as a container. Each Submenu block has a parent link and child items that appear on hover (desktop) or tap (mobile). The block editor handles the visual hierarchy — users drag items into a Submenu block to create the dropdown structure.
As a theme developer, you control dropdown behavior and styling through CSS. The Navigation block generates CSS classes that you can target:
- .wp-block-navigation__submenu-container: The dropdown container that shows and hides
- .wp-block-navigation-submenu: The parent item that triggers the dropdown
- .wp-block-navigation-submenu__toggle: The dropdown toggle arrow/button
- has-child: Class added to items that have a submenu
For styling dropdown behavior, most themes need to customize the dropdown width, background color, shadow, border radius, and animation. These should be defined in your theme’s CSS using the block CSS classes rather than overriding the block’s inline styles. Use your theme.json color presets so dropdown styles adapt when users change the color palette through Global Styles.
Multi-Level Dropdowns
The Navigation block supports nested submenus — dropdowns within dropdowns — up to three levels deep by default. Each level gets a .wp-block-navigation__submenu-container class, and nested levels are positioned relative to their parent. For most sites, two levels (parent → child) is sufficient. Three-level menus are technically supported but can create usability problems on both desktop (hard to navigate with hover) and mobile (confusing nested accordions).
Theme developers should consider capping dropdown depth at two levels and communicating this constraint in their theme documentation. If users need more complex navigation hierarchies, recommend using a mega menu pattern instead of deeply nested dropdowns.
Mobile Navigation: The Overlay Menu
The Navigation block handles mobile responsiveness through its overlay menu system. When the overlayMenu attribute is set to “mobile”, the block automatically switches from a horizontal desktop menu to a full-screen or slide-in overlay on narrow viewports. The breakpoint is determined by the block’s own responsive logic, typically triggering around 600px viewport width.
The mobile overlay has several components you can style:
- .wp-block-navigation__responsive-container: The overlay wrapper
- .wp-block-navigation__responsive-container-open: The hamburger toggle button
- .wp-block-navigation__responsive-container-close: The close button inside the overlay
- .wp-block-navigation__responsive-dialog: The dialog content area
The overlay menu uses the HTML dialog element for proper focus management and accessibility. When opened, focus is trapped within the overlay, the background content receives an inert attribute, and pressing Escape closes the menu. This built-in accessibility behavior is significantly more robust than most custom mobile menu implementations.
Customizing the Mobile Menu Transition
By default, the overlay menu appears instantly. Most themes add a CSS transition for a smoother experience. Target the .wp-block-navigation__responsive-container class with opacity and transform transitions. A common pattern is a slide-in from the right with a slight opacity fade, taking 200 to 300 milliseconds. Keep the transition duration short — mobile users expect fast, responsive interactions.
You can also customize the overlay’s visual design: full-screen overlay (background covers the entire viewport), slide-in panel (menu slides from one side, background dims), or dropdown panel (menu drops down from the header). Each approach requires different CSS targeting the responsive container classes. Choose the pattern that matches your theme’s design language and test thoroughly on actual mobile devices.
Building a Mega Menu Pattern
Mega menus display rich content in a full-width dropdown panel instead of a narrow submenu list. They are common on e-commerce sites and content-heavy websites. The Navigation block does not natively support mega menus, but you can build them using a combination of the Submenu block with custom block patterns and CSS.
The approach involves creating a Submenu block with a Group block as its content, styled to display as a full-width panel. Inside the Group, you place Columns blocks with links, images, descriptions, or any other blocks. The CSS targets the .wp-block-navigation__submenu-container class within a specific menu item and overrides the default narrow dropdown styling with full-width positioning.
Key CSS for mega menus:
- Set position: static on the parent submenu item (removes relative positioning)
- Set width: 100vw and left: 50% with transform: translateX(-50%) on the submenu container to make it full-width
- Use CSS Grid or Flexbox for the internal column layout
- Add a max-height with overflow-y: auto for menus with many items
Document your mega menu implementation thoroughly in your theme’s documentation, as users will need guidance on how to add content to the mega menu panel through the block editor. Consider shipping a mega menu pattern that users can insert into the Navigation block directly.
Navigation Accessibility Best Practices
The Navigation block generates accessible markup by default, but theme developers can inadvertently break accessibility through custom CSS or JavaScript:
- Never hide the focus indicator. The default focus ring on menu items is essential for keyboard users. If the default style conflicts with your design, replace it with a visible custom focus style — never remove it with outline: none.
- Maintain sufficient color contrast. Menu text against menu background must meet WCAG 2.1 AA standards (4.5:1 contrast ratio for normal text). This applies to all states: default, hover, focus, and active. Test both the desktop menu and mobile overlay.
- Do not override ARIA attributes. The Navigation block sets aria-label, aria-expanded, aria-haspopup, and role attributes correctly. Custom JavaScript that modifies these attributes can break screen reader navigation.
- Test keyboard navigation end-to-end. Tab through every menu item, open and close submenus with Enter and Escape, and verify that focus moves logically. Dropdown menus should trap focus within the submenu when open and return focus to the parent item when closed.
- Provide a skip navigation link. Include a “Skip to content” link before the Navigation block that becomes visible on focus. This lets keyboard users bypass the menu to reach the main content directly. Many block themes include this in the header template part as a hidden link that appears on keyboard focus.
Performance Considerations
Navigation menus affect every page load on your site, so performance matters:
- Keep menu items under 10 for the primary navigation. Each menu item adds DOM nodes and event listeners. Aim for 5 to 7 top-level items with submenus handling additional pages.
- Avoid images in navigation. Some themes add icons or thumbnails to menu items. While visually appealing, each image adds an HTTP request and increases the critical rendering path. Use CSS-based icons (SVG inline or icon fonts) instead of image files.
- Minimize custom JavaScript. The Navigation block handles interactivity (dropdowns, mobile toggle) natively. Adding custom JavaScript for hover effects, scroll-triggered behaviors, or animation can conflict with the block’s built-in functionality and add unnecessary overhead. If you need custom behavior, use the Interactivity API instead of vanilla JavaScript for better integration with the block ecosystem.
- Lazy-load mega menu content. If your mega menu includes images or complex content, consider lazy-loading the submenu content so it only loads when the user opens the dropdown, not on initial page load.
Conditional Navigation: Different Menus for Different Pages
Some sites need different navigation menus on different pages — a simplified menu on landing pages, a full menu on content pages, or a logged-in user menu that differs from the logged-out menu. Block themes handle this through custom templates and template parts.
Create multiple header template parts (header-landing.html, header-minimal.html) with different Navigation block configurations. Then create custom templates that use different header parts. Assign the appropriate custom template to specific pages through the page editor’s Template selector.
For user-state-dependent navigation (logged in vs logged out), you need PHP logic in functions.php. Use the block_type_metadata filter or a custom block pattern with PHP logic to conditionally render different navigation content based on the user’s authentication state. This approach maintains the block theme’s declarative template model while adding the dynamic behavior where needed.
Styling Navigation with theme.json
theme.json provides per-block styling for the Navigation block through the styles.blocks.core/navigation section. You can set default colors, typography, spacing, and other properties that apply to every Navigation block instance in your theme:
The theme.json approach ensures your navigation styling respects the Global Styles cascade. Users can override your defaults through the Site Editor’s Styles panel, and their changes take precedence over theme.json values. This is the correct behavior — theme.json sets sensible defaults, users customize as needed.
For more detailed customization of header and footer template parts that contain navigation, including layout patterns and responsive design strategies, see our dedicated template parts guide.
Migrating from Classic Menus to the Navigation Block
If you are converting a classic theme to a block theme, migrating existing menus to the Navigation block is one of the most visible changes your users will notice. WordPress handles this migration automatically in many cases — when you switch from a classic theme to a block theme, WordPress attempts to convert your existing classic menu items into a wp_navigation post that the Navigation block can reference.
However, automatic migration has limitations. Custom CSS classes assigned to menu items may not transfer. Menu item descriptions are not always preserved. Conditional display rules from plugins like Menu Items Visibility Control are lost because the Navigation block does not support conditional display natively. Before migrating, document your current menu structure including any custom classes, descriptions, and conditional rules so you can recreate them in the block theme context.
For themes that need to support both classic and block editing (hybrid themes), you can register a classic menu as a fallback while providing a Navigation block as the primary interface. Use the wp_nav_menu function in a classic template part as a fallback, and the Navigation block in the block template part. This dual approach lets existing users keep their classic menus while new users get the full block editing experience.
Navigation Block Patterns for Common Layouts
Shipping pre-built navigation patterns with your theme saves users significant setup time. Here are the most common navigation patterns that production themes should include:
Standard horizontal navigation is the most common pattern: logo on the left, menu items centered or right-aligned, with a CTA button as the last item. The button is a standard Page Link or Custom Link block with the “outline” or “fill” button style applied via the block’s style variation. This pattern uses a Row block to arrange logo and navigation side by side with space-between justification.
Centered logo with split navigation places the logo in the center with menu items split on either side. This requires two Navigation blocks — one for the left items and one for the right items — with the Site Logo block between them. All three are arranged in a Row block. This pattern is popular for restaurant, portfolio, and fashion websites.
Stacked header with navigation bar puts the logo and tagline in a top row, with a full-width navigation bar below in a contrasting background color. This uses two Group blocks stacked vertically — the top Group contains the Site Logo and Site Title, the bottom Group has a different background color and contains the Navigation block. This pattern works well for news sites and content-heavy websites that need prominent navigation.
Transparent header overlay positions the navigation over hero content with a transparent background. The header template part uses a Group block with no background color and position: absolute or sticky CSS. Menu items use light text colors that contrast against the hero image below. This pattern requires careful z-index management and should include a scroll-triggered background color change (using the Interactivity API or custom CSS with scroll-driven animations) so menu items remain readable as the user scrolls past the hero section.
Troubleshooting Common Navigation Issues
Mobile menu does not open. Check that no JavaScript error is blocking the dialog element. Inspect the browser console for errors. A common cause is a conflicting plugin that also tries to manage mobile navigation. Deactivate plugins one at a time to identify the conflict. Also verify that the overlayMenu attribute is set to “mobile” or “always” in the block markup.
Dropdown menus appear behind other content. This is a z-index issue. The navigation submenu container needs a higher z-index than surrounding content. Add CSS targeting .wp-block-navigation__submenu-container with a z-index of 100 or higher. If your theme uses sticky positioning on the header, the header also needs an appropriate z-index.
Menu items do not wrap on medium-sized screens. Between desktop (full menu) and mobile (overlay menu), there is often a viewport range where menu items overflow their container. The Navigation block handles this by switching to the overlay at a specific breakpoint, but if your menu has many items, the transition point may not be ideal. Adjust the overlay trigger by adding custom CSS that forces the overlay to appear at a wider viewport using media queries targeting the responsive container classes.
Navigation loses styling after theme update. If your Navigation block styles reset after updating WordPress or your theme, the issue is likely that inline styles are being overridden by updated block CSS. Move your navigation styling from inline styles (set through the block editor UI) to theme.json’s styles.blocks section, which has proper cascade priority and survives updates.
Submenus open in the wrong direction. On pages where the navigation is near the right edge of the viewport, dropdown submenus may overflow off-screen to the right. WordPress does not automatically flip submenu direction. Add CSS that uses the :last-child or :nth-last-child selector on top-level menu items to position their submenus to open left instead of right, or use a JavaScript solution that checks available viewport space and adjusts positioning dynamically.
Navigation and SEO: What Theme Developers Should Know
Navigation structure directly affects how search engines crawl and index your site. The Navigation block generates clean, semantic HTML that search engines can parse easily, but your implementation choices still matter for SEO performance.
Internal linking through navigation is one of the strongest ranking signals you can control. Every page linked in your primary navigation receives link equity from every page on your site, since the navigation appears on every page. This means your most important pages — services, products, key content hubs — should be in the primary navigation. Pages that are less important for SEO (privacy policy, terms of service) belong in the footer navigation instead.
The Navigation block generates proper anchor text from the link label, which helps search engines understand what each linked page is about. Avoid generic labels like “Click Here” or “Learn More” as navigation items. Use descriptive labels that include relevant keywords naturally — “WordPress Themes” is better than “Our Products” from an SEO perspective.
For large sites with hundreds of pages, navigation depth matters for crawl budget. Pages that are more than three clicks from the homepage receive less crawl attention from search engines. Use your navigation hierarchy strategically: top-level items for category pages, submenus for important individual pages, and rely on internal linking within content for deeper pages. Breadcrumbs complement navigation by showing search engines the site hierarchy and providing additional internal links to category and parent pages.
Mobile navigation also affects SEO because Google uses mobile-first indexing. The Navigation block’s overlay menu renders all menu items in the HTML even when collapsed, so search engines can still see and follow the links. However, if you use JavaScript to dynamically load menu items only when the overlay opens, those links may not be visible to crawlers. Stick with the Navigation block’s default rendering behavior to ensure all navigation links are crawlable.
Frequently Asked Questions
Can I use the Navigation block in a classic theme?
The Navigation block is designed for block themes that use Full Site Editing. Classic themes use wp_nav_menu() in PHP templates instead. However, you can use the Navigation block within individual post or page content in a classic theme — it just cannot replace your theme’s primary header navigation unless the theme is converted to a block theme. Hybrid themes that support both classic and block editing can offer the Navigation block as an option alongside classic menus during the transition period.
How do I add a search bar to the Navigation block?
The Navigation block supports the Search block as an inner block. In the Site Editor, click inside the Navigation block, add a new block, and select the Search block. It will appear as a search icon or input field within your navigation bar. You can control whether it displays as an icon that expands on click or as a persistent search field through the Search block’s settings. Style the search block using theme.json under styles.blocks.core/search to match your navigation design.
Why does my Navigation block show “Navigation menu has been deleted” error?
This error appears when the wp_navigation post referenced by the block’s ref attribute has been deleted or moved to trash. This can happen when switching themes, importing content, or accidentally deleting the navigation post from the WordPress admin. To fix it, open the Site Editor, select the Navigation block, and choose an existing navigation menu from the block settings or create a new one. If you need to recover a deleted navigation, check the trash in the WordPress admin under the wp_navigation post type.
How many navigation menus can a block theme support?
Block themes can support unlimited navigation menus. Each wp_navigation post is an independent menu, and you can place Navigation blocks in any template or template part. Most themes use at least two navigations — a primary menu in the header and a secondary menu in the footer. You can also create separate navigations for sidebars, mobile-specific menus, or contextual navigation within specific templates. The only practical limit is usability: too many different navigation menus confuse users and dilute the site’s information architecture.
Summary
The Navigation block is far more capable than the classic menu system it replaces. It provides built-in accessibility, responsive behavior, visual editing, and extensibility through standard block editor patterns. As a theme developer, your role is to provide sensible defaults through template markup and theme.json styling, ship clear documentation for users who need advanced features like mega menus, and test thoroughly across devices and assistive technologies. Master the Navigation block and you master one of the most visible and frequently interacted-with elements on any WordPress site.