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