Payload Advanced Sidebar

A Payload CMS 3.0 plugin that enhances your admin sidebar navigation. It allows you to assign custom icons to your collection/global groups as well as individual items, making your admin interface much more visually appealing and organized.

Features

• 📁 Group Icons: Assign custom icons to the sidebar groups you've defined in your Payload config.
• 🔗 Custom Nav Links: Add fully custom items and custom groups that point to external sites or custom Payload views.
• 🎨 Item Icons: Assign custom icons to individual collections and globals.
• ⚡️ Lucide React Integration: Uses Lucide React icons by default. Just pass the exact string name of the icon (e.g., 'ShoppingCart').
• ⚙️ Simple Configuration: Seamlessly integrates with your existing Payload config without needing to rewrite your navigation structure.

Installation

npm install payload-advanced-sidebar
# or
yarn add payload-advanced-sidebar
# or
pnpm add payload-advanced-sidebar

Usage

This plugin relies on the standard admin.group property you define on your collections and globals in Payload. You simply map those group names or item slugs to an icon!

Add the plugin to your payload.config.ts:

import { buildConfig } from 'payload/config'
import { advancedSidebarPlugin } from 'payload-advanced-sidebar'

export default buildConfig({
  collections: [
    {
      slug: 'posts',
      admin: { group: 'Content' }, // The group name used below
      fields: [],
    },
    {
      slug: 'customers',
      admin: { group: 'E-commerce' }, // The group name used below
      fields: [],
    }
  ],
  plugins: [
    advancedSidebarPlugin({
      enabled: true, // Optional: defaults to true
      // 1. Configure icons for your navigation groups
      groups: {
        'E-commerce': {
          icon: 'ShoppingCart', // String matching a Lucide React icon
        },
        'Content': {
          icon: 'LayoutDashboard',
        },
      },
      // 2. Configure icons for specific items (by slug)
      items: {
        'posts': {
          icon: 'Book',
        },
        'customers': {
          icon: 'Users',
        },
      },
      // 3. Add custom navigation links or groups
      navLinks: [
        {
          label: 'Custom Dashboard',
          path: '/custom-dashboard', // relative to adminRoute
          icon: 'Activity',
          group: 'Analytics', // Creates a new 'Analytics' group
        },
        {
          label: 'External Link',
          path: 'https://payloadcms.com',
          icon: 'ExternalLink',
          group: 'E-commerce', // Adds to existing 'E-commerce' group
        },
      ],
    }),
  ],
})

Plugin Options

Option	Type	Default	Description
enabled	boolean	true	Set to false to easily disable the plugin entirely.
animations	boolean	true	Set to false to disable smooth expanding/collapsing animations for sidebar groups.
groups	Record<string, { icon?: string }>	{}	Map your group names (e.g., 'E-commerce') to specific Lucide React icon names.
items	Record<string, { icon?: string }>	{}	Map your collection/global slugs (e.g., 'posts') to specific Lucide React icon names.
navLinks	CustomNavLink[]	[]	Array of custom navigation links, allowing you to add external URLs or internal custom routes to existing or new groups.

Development

To develop or contribute to this plugin:

1. Clone the repository
2. Run pnpm install
3. Run pnpm dev to start the development server
4. Edit the files in the src directory

License

MIT