Payload CMS Navigation Plugin

A flexible and powerful navigation management plugin for Payload CMS, enabling easy creation and management of navigation menus for your website.

Installation

# Using pnpm
pnpm add payload-cms-navigation-plugin

Features

• Create multiple navigation containers (menus)
• Support for hierarchical navigation structures (nested menus)
• Different types of navigation items (internal links, external URLs, folders)
• Localization support with locale-specific visibility
• Flexible API with multiple output formats (tree, flat, breadcrumbs)
• Admin UI integration with Payload CMS
• Highly customizable

Configuration

Add the navigation plugin to your Payload CMS configuration:

import { buildConfig } from 'payload/config'
import { navigationPlugin } from 'payload-cms-navigation-plugin'

export default buildConfig({
  // Your existing Payload config
  plugins: [
    navigationPlugin({
      // Optional: Configure which collections can be referenced in navigation
      collections: {
        pages: true,
        'blog-posts': true,
        // Add any collections you want to be available for internal links
      },

      // Optional: Localization settings
      localization: {
        localeVisibility: true, // Enable locale-specific visibility
      },
    }),
    // Your other plugins
  ],
})

Core Concepts

Navigation Containers

Navigation containers represent a complete menu structure, such as a "Main Menu", "Footer Navigation", or "Sidebar Menu". Each container has:

• Unique name and slug
• Collection of root-level navigation items
• Settings for maximum depth and allowed item types

Navigation Items

Navigation items are the individual elements within a navigation container. They can be:

• Internal Links: References to content from other collections (pages, blog posts, etc.)
• External URLs: Links to external websites
• Folders: Group items without being a link themselves

Items can be nested within each other to create hierarchical structures.

API

REST Endpoints

The plugin adds the following REST endpoints:

Get All Navigation Containers

GET /api/navigation-containers

Query Parameters:

• locale (optional): Specify a locale for localized content

Get Single Navigation Container

GET /api/navigation-containers/:slug

Query Parameters:

• locale (optional): Specify a locale for localized content
• depth (optional): Control the depth of nested items (default: 1)
• format (optional): Output format - 'tree', 'flat', or 'breadcrumb' (default: 'tree')
• includeHidden (optional): Whether to include hidden items (default: false)
• item (optional): Current item ID for breadcrumb generation

Update Navigation Container

PATCH /api/navigation-containers/:id

Body:

• items: Array of navigation items to update

Query Parameters:

• locale (optional): Specify a locale for localized content

Usage Examples

Fetching Navigation Data (Client-Side)

// Fetch a navigation container by slug
const response = await fetch('/api/navigation/main-menu?depth=2&format=tree')
const navigation = await response.json()

// Render navigation with your preferred method

Displaying Navigation (React Example)

function Navigation({ container }) {
  const renderItems = (items) => {
    return (
      <ul>
        {items.map((item) => (
          <li key={item.id} className={item.className || ''}>
            {item.type === 'folder' ? (
              <>
                <span>{item.title}</span>
                {item.items?.length > 0 && renderItems(item.items)}
              </>
            ) : (
              <a href={item.path} target={item.target || '_self'}>
                {item.title}
              </a>
            )}
            {item.items?.length > 0 && renderItems(item.items)}
          </li>
        ))}
      </ul>
    )
  }

  return <nav>{renderItems(container.items)}</nav>
}

Customization

The plugin is designed to be flexible and can be customized in various ways:

• Configure which collections can be referenced in navigation
• Set locale-specific visibility rules
• Customize the maximum depth for nested navigation
• Restrict allowed navigation item types per container

Contributing

Contributions are welcome! Feel free to submit issues or pull requests.

License

MIT