---
title: "Folders — Content Organization"
aliases: [payload-folders, payload-content-folders]
tags: [payloadcms, folders, organization, collections, beta]
sources: [raw/folders__overview.md]
created: 2026-05-15
updated: 2026-05-15
---

## Overview

Folders let you group documents across collections. Built on top of [[wiki/payloadcms/fields|relationship 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)

```ts
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

```ts
{
  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

## Related

- [[wiki/payloadcms/features|Features — Email, Folders, Trash, Query Presets]]
- [[wiki/payloadcms/fields|Field Types Reference]]
- [[wiki/payloadcms/admin-panel-overview|Admin Panel Overview]]
- [[wiki/payloadcms/queries|Queries — Where, Sort, Pagination]]

## Sources

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