obsidian/wiki/payloadcms/folders.md at d18653ff63d0c19056c38271ba8a02642ee10ff0

Vadym/obsidian

Fork 0

Vadym Samoilenko a3c61e91c4 vault backup: 2026-05-15 15:42:42

2026-05-15 15:42:42 +01:00

2.9 KiB

Raw Blame History

title

aliases

Overview

Folders let you group documents across collections. Built on top of wiki/payloadcms/fields — enabling a folder adds a hidden folder relationship field to each document. Folders can nest within other folders.

Beta warning: Folders feature is in beta and may change in minor versions before stable.

Configuration

Two config locations: global (payload.config.ts) and per-collection.

Global (payload config)

import { buildConfig } from 'payload'

const config = buildConfig({
  folders: {
    browseByFolder: true,      // default: true — enables browse-by-folder view
    debug: false,              // default: false — shows hidden folder fields/collections
    fieldName: 'folder',       // default: 'folder' — hidden field name on documents
    slug: 'payload-folders',   // default: 'payload-folders' — internal collection slug
    collectionOverrides: [     // optional — plugins can mutate the folder collection
      async ({ collection }) => collection,
    ],
  },
})

Per-Collection

{
  slug: 'pages',
  folders: true,  // simplest form — defaults to false
}

// Or with options:
{
  slug: 'pages',
  folders: {
    browseByFolder: true,  // include this collection in browse-by-folder view
  },
}

folders: true adds a hidden relationship field pointing to the folder collection (or null = no folder).

How It Works

Payload creates an internal payload-folders collection (slug configurable)
Each folder document has its own folder field → enables nesting
Collections opt-in via folders: true — no effect on others
The hidden field name defaults to folder but is configurable via fieldName

Key Takeaways

Opt-in per collection — set folders: true in collection config; off by default
Nested folders — folders themselves have a folder field, so trees are supported
Browse view — browseByFolder: true enables a dedicated browse UI in the admin panel
Debug mode — debug: true surfaces the hidden folder fields/collections in the UI (useful during development)
Slug override — if payload-folders conflicts with existing collections, override via slug
Beta — API/config shape may change before stable; pin minor versions if upgrading

Sources

raw/folders__overview.md — https://payloadcms.com/docs/folders/overview

2.9 KiB Raw Blame History