Adding Descriptions to Navigation Submenu Items in WordPress

Today, I’m here to address a question from a fellow WordPress user, oshka, who was facing a challenge when trying to display descriptions for menu items with children in the Navigation block.

As they pointed out, it seems there’s no built-in logic for rendering descriptions in the Navigation submenu in WordPress.

Customizing your Navigation Menu can enhance your website’s user experience.

So, how can we tackle this issue and make your Navigation Submenu shine with descriptive content? 🤔

Descriptions to Navigation Submenu Items in WordPress

Well, Oshka found a clever solution using WordPress Filter hooks, and I’m going to break it down for you step by step.

Step 1: Create a Custom Function

To kickstart the process, you’ll need to create a custom function using the render_block filter hook. This function will let you alter the HTML output for your Navigation Submenu block.

Step 2: Define Conditions

Inside your custom function, set up conditions to ensure that your modifications are only applied where necessary:

  • Target the specific block type, in this case, ‘core/navigation-submenu.’
  • Ensure that the modifications are only rendered on the front-end.
  • Don’t alter the HTML in wp-json requests.

Step 3: Check for Descriptions

Within your custom function, check if title or description attributes are available for the Navigation Submenu. If they are, you’ll create a new list item element to accommodate these details.

Step 4: Insert Your Content

Identify the position to insert your additional HTML content. You want to add your descriptions right after the opening <ul> tag of your Navigation Submenu.

Step 5: Implement Your Filter

Finally, add your filter using the add_filter function. This will ensure that your custom rendering function is applied when necessary.

Now, let’s take a look at a simplified example of what your custom function might look like:

function custom_render_block_core_navigation_submenu(string $block_content, array $block): string
    if (
        isset($block['blockName']) &&
        'core/navigation-submenu' === $block['blockName'] &&
        !is_admin() &&
    ) {
        $additional_html = '';

        if (!empty($block['attrs']['title']) || !empty($block['attrs']['description'])) {
            $additional_html .= '<li class="wp-block-navigation-item">';

            if (!empty($block['attrs']['title'])) {
                $additional_html .= '<span class="wp-block-navigation-item__label">';
                $additional_html .= wp_kses_post($block['attrs']['title']);
                $additional_html .= '</span>';

            if (!empty($block['attrs']['description'])) {
                $additional_html .= '<span class="wp-block-navigation-item__description">';
                $additional_html .= wp_kses_post($block['attrs']['description']);
                $additional_html .= '</span>';

            $additional_html .= '</li>';

        $position = strpos($block_content, '<ul class="wp-block-navigation__submenu-container wp-block-navigation-submenu">');

        if ($position !== false) {
            $position += strlen('<ul class="wp-block-navigation__submenu-container wp-block-navigation-submenu">');
            $block_content = substr_replace($block_content, $additional_html, $position, 0);

    return $block_content;

add_filter('render_block', 'custom_render_block_core_navigation_submenu', null, 2);

And there you have it!

By following these steps, you can now render descriptions for submenu items in your Navigation block. This enhanced functionality can provide your website visitors with more information and improve the user experience. 🚀

If you’re eager to take your WordPress skills to the next level and learn more about customizing your website, feel free to explore the WordPress documentation and community forums for further guidance.

Have you encountered a similar challenge in WordPress or have other questions related to web development? Let’s keep the conversation going! Share your thoughts and questions below. 💬👇

Leave a Comment