WordPress navigation blocks

I’ve found out how to do a navigation block (a menu) for pages, at least, in WordPress (WP) block themes. I found out by looking in the block themes available in the WP directory. In one of your HTML files (in my-theme/templates/ or my-theme/parts), perhaps in the header, you need to add the following:

<!-- wp:navigation /-->

This will produce a very basic horizontal menu that supports sub-menus.

The following markup seems to pertain specifically to the navigation block (forgive the lack of sensible order and styling: it was too daunting to edit the raw HTML):

A non-exhaustive list of markup that can be used to style the wp:navigation block
Key Value
layout*type
justifyContent
setCascadingProperties
orientation
orientationhorizontal
vertical
itemsJustificationcenter
right
typeflex
justifyContentcenter
right
left
showSubmenuIconfalse
overlayMenunever
always
mobile
setCascadingPropertiestrue
isResponsivetrue
openSubmenusOnClicktrue
overlayBackgroundColor<colour name> e.g. “dark”, “primary”, “background”
overlayTextColor<colour name> e.g. “white”
__unstableLocationprimary
navigationMenuId<integer> e.g. 12
flexWrapwrap
__unstableSocialLinkssocial

*The values of the layout markup keys are keys themselves; use them like this:

<!-- wp:navigation {"layout":{"type":"flex","justifyContent":"center}} /-->

I don’t know what the significance of the initial double underscore is. I noticed it in the WeCodeArt and Stewart themes, amongst others. Update: Bican Marian Valeriu of WeCodeArt says that the initial double underscore means that that WP Core feature is ‘experimental and it might change in the future’.

I suspect this is the name of a menu position, but I’m not sure.

WP navigation link, WP navigation submenu

There’s also wp:navigation-link and wp:navigation-submenu:

A non-exhaustive list of markup that can be used to style the wp:navigation-link and wp:navigation-submenu blocks
Key Value
label<string> e.g. “Home”, “About”, “Blog”, “Privacy Policy”
url<url>
kindcustom
post-type
isTopLevelLinktrue
false
typepage
title<string> e.g. “Home”, “About”, “Blog”, “Privacy Policy”
id<integer> e.g. 223

Usage seems to be as follows, nested in the navigation block:

<!-- wp:navigation -->
  <!-- wp:navigation-link {"label":"Home","url":"/about","kind":"custom","isTopLevelLink":true} /-->
  <!-- wp:navigation-link {"label":"About","url":"/about","kind":"custom","isTopLevelLink":true} /-->
  <!-- wp:navigation-link {"label":"Blog","url":"/blog","kind":"custom","isTopLevelLink":true} /-->
  <!-- wp:navigation-link {"label":"Contact","url":"/contact","kind":"custom","isTopLevelLink":true} /-->
<!-- /wp:navigation -->

Notice that what is normally a tag with no explicit close tag has become a tag with an explicit close tag.

WP page list

There is also a wp:page-list that can be styled using markup:

A non-exhaustive list of markup that can be used to style the wp:pagelist block
Key Value
isNavigationChildtrue
showSubmenuIcontrue
openSubmenusOnClicktrue

It also seems to be used inside the WP navigation block:

<!-- wp:navigation --><!-- wp:page-list /--><!-- /wp:navigation -->

Your guess is as good as mine as to what some of these keys and values do. Some of them seem obvious, but others are clouded in a little more mystique.

2 thoughts on “WordPress navigation blocks

  1. Being the developer of WeCodeArt theme I can tell you what the __ significance is 🙂 . That means the feature is added to WP Core but at the moment is marked as experimental and it might change in the future.

    1. Ah, I see. That makes sense. Thanks for taking the time to tell me, Bican Marian Valeriu 🙂

      I’ve updated the footnote accordingly.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.