Navigation menu

ButterCMS Collections are a great fit to store navigation menu data, as they’re both flexible and restricted to simple data types. With a ButterCMS Collection, you can also:

add logos and images
enforce validation for strings, numbers, and URLs
nest multiple levels of navigation

For a full breakdown of ButterCMS Collections, check out our core concepts article.

Follow the below steps to create a simple, flat menu with the following hierarchy:

Main menu

Home

About

Features

Try it

Testimonials

Blog

Create the Menu Item Collection

First, build the schema for your menu items. Important fields include:

Label - The display text
URL - What the item links to

Save it as “Navigation Menu Item”: Save as Navigation Menu Item

Create the Parent Menu Collection

Need more features than Collections allow? You can also use a Page to hold the Reference fields for your menu items.

Create a second Collection for the main menu that references the menu items:

Name - The navigation menu name
Menu Items - A Reference field linking to Navigation Menu Item (One-to-Many)

Add Menu Items

Click New item to add items to your Collection: Add new item button

Add each navigation item with its label and URL: Navigation Menu Item entry

Link Items to the Menu

In your main Navigation Menu, click Add Reference and select all the items you want: Linking menu items via reference

For complex menus with multiple levels, create separate Collections for each level. Here’s an example hierarchy: Complex multi-level navigation menu

Create third-level collection

Start with the lowest-level children. Create “Menu - Third Level”: Third level menu item schema

Create second-level collection

“Menu - Second Level” includes a Reference field linking to Third Level: Second level with reference to third

Create first-level collection

“Menu - First Level” references Second Level: First level with reference to second

Populate the collections

Add items to each level:Third Level: Third level menu items

Second Level: Second level menu items

First Level: First level menu items

Link collections together

Use the Add Reference button to connect items from one Collection to another: Linking collections via reference

Header with logo and links
Footer navigation
E-commerce

Collection schema for Header Navigation:

Field	Type	Purpose
`logo`	Media	Site logo image
`logo_alt`	Short Text	Alt text for logo
`menu_items`	Reference	Links to Navigation Menu Items
`cta_button_text`	Short Text	Call-to-action text
`cta_button_url`	Short Text	CTA destination URL

Collection schema for Footer:

Field	Type	Purpose
`company_name`	Short Text	Business name
`tagline`	Long Text	Footer description
`column_1_title`	Short Text	First column heading
`column_1_links`	Reference	Links for column 1
`column_2_title`	Short Text	Second column heading
`column_2_links`	Reference	Links for column 2
`social_links`	Repeater	Social media icons and URLs
`copyright_text`	Short Text	Copyright notice

For e-commerce or content-rich sites:

Field	Type	Purpose
`category_name`	Short Text	Category title
`category_image`	Media	Featured image
`featured_item`	Reference	Highlighted product/page
`links`	Reference	Sub-items
`promo_banner`	Media	Promotional image
`promo_url`	Short Text	Promo destination

JavaScript/Node.js

const Butter = require('buttercms');
const butter = Butter('your-api-token');

// Fetch navigation menu
const getNavigation = async () => {
  const response = await butter.content.retrieve(['navigation_menu'], {
    'fields.name': 'Main Menu'
  });

  return response.data.data.navigation_menu[0];
};

// Example response structure
{
  "name": "Main Menu",
  "menu_items": [
    { "label": "Home", "url": "/" },
    { "label": "About", "url": "/about" },
    { "label": "Features", "url": "/features" }
  ]
}

const getComplexNavigation = async () => {
  // Fetch all levels with nested references
  const response = await butter.content.retrieve([
    'menu_first_level'
  ], {
    levels: 3 // Fetch nested references up to 3 levels deep
  });

  return response.data.data.menu_first_level;
};

React component

import { useEffect, useState } from 'react';
import Butter from 'buttercms';

const butter = Butter('your-api-token');

const Navigation = () => {
  const [menu, setMenu] = useState(null);

  useEffect(() => {
    const loadMenu = async () => {
      const response = await butter.content.retrieve(['navigation_menu'], {
        'fields.name': 'Main Menu'
      });
      setMenu(response.data.data.navigation_menu[0]);
    };

    loadMenu();
  }, []);

  if (!menu) return null;

  return (
    <nav>
      <ul>
        {menu.menu_items.map(item => (
          <li key={item.url}>
            <a href={item.url}>{item.label}</a>
          </li>
        ))}
      </ul>
    </nav>
  );
};

export default Navigation;

Performance tips

For global API calls like header and footer navigation, cache the response. A cache duration of 5-10 minutes is typical, or use on-demand revalidation when content changes via webhooks.

Cache navigation responses at the edge or in your app layer (5-10 minutes is typical).
Use levels sparingly to avoid oversized responses for deep menus.

Best practices

Content modeling

Separate concerns: Use different Collections for header vs footer
Include icons: Add optional Media fields for menu item icons
Support external links: Include a checkbox for “Open in new tab”
Add ordering: Use a Number field if you need custom sort order

Accessibility

Use semantic HTML: <nav>, <ul>, <li> elements
Add ARIA labels: aria-label, aria-expanded for dropdowns
Keyboard navigation: Ensure all items are focusable
Mobile considerations: Include hamburger menu for small screens

Modeling your menu in ButterCMS

Create a single level menu

Building a complex multi-level menu

Common navigation patterns

Fetching navigation via API

JavaScript/Node.js

Multi-level menu fetch

React component

Performance tips

Best practices

​Modeling your menu in ButterCMS

​Create a single level menu

​Building a complex multi-level menu

​Common navigation patterns

​Fetching navigation via API

​JavaScript/Node.js

​Multi-level menu fetch

​React component

​Performance tips

​Best practices

Modeling your menu in ButterCMS

Create a single level menu

Building a complex multi-level menu

Common navigation patterns

Fetching navigation via API

JavaScript/Node.js

Multi-level menu fetch

React component

Performance tips

Best practices