Payload Tree View

A Payload CMS plugin that replaces the default list view with a hierarchical tree view for collections that have self-referencing parent fields.

Built for Payload v3.37+.

Installation

npm install @byte5digital/payload-tree-view
# or
yarn add @byte5digital/payload-tree-view

Important: After installing, you must regenerate Payload's import map for the plugin's custom components to be picked up:

yarn generate:importmap

Usage

Add the plugin to your Payload config and specify which collections should use the tree view:

import { buildConfig } from 'payload'
import { payloadTreeView } from '@byte5digital/payload-tree-view'

export default buildConfig({
  // ...
  plugins: [
    payloadTreeView({
      collections: {
        pages: true, // uses 'parent' field by default
        categories: {
          parentField: 'parentCategory', // custom parent field name
          allowToggle: false, // disable switching back to list view
        },
      },
    }),
  ],
})

Your collection must have a self-referencing relationship field (e.g. a parent field that relates to the same collection). The plugin reads this field to build the hierarchy.

Configuration

Plugin Options

| Option | Type | Description | | ------------- | -------- | ------------------------------------------------ | | collections | object | Map of collection slugs to tree view config | | disabled | boolean| Disable the plugin without removing it |

Per-Collection Options

Pass true to use defaults, or an object:

| Option | Type | Default | Description | | ------------- | -------- | ---------- | ------------------------------------------------ | | parentField | string | 'parent' | Name of the self-referencing relationship field | | allowToggle | boolean| true | Allow users to switch between tree and list views |

Features

• Hierarchical tree view with expand/collapse controls
• Expand all / collapse all buttons
• Toggle between tree view and default list view (can be disabled per collection)
• Preserves Payload's list chrome: filters, search, sorting, bulk actions, and column selection
• View mode preference persisted in localStorage
• Supports relationship fields rendered as thumbnails (upload collections)
• Orphaned documents (with missing/deleted parents) appear as root nodes

Tree View

Development

pnpm build        # Build the plugin
pnpm lint         # Run ESLint
pnpm lint:fix     # Fix lint issues
pnpm test:int     # Run unit tests (vitest)
pnpm test:e2e     # Run E2E tests (Playwright)

License

MIT