RFC: Collection Specific Folders

[JarrodMFlesch]

Background

Currently folders are global — meaning that folders created from any folder enabled collection will also be visible when browsing other folder enabled collections. Say you have folders on the users collection that models the structure of departments in your company:

Users (collection)
├── Engineering (folder)
├── Design (folder)
├── Marketing (folder)
└── Sales (folder)

When you go the posts collection you will see these folders there as well and that might be confusing. You might see this and think: "wait, why do the folders I created in the users collection also appear in the posts collection folders?"

Why did we choose global?

We think it is important that all folders should be able to store multiple collection types, similar to Google Drive. This way you can create folders for specific groupings of items across collection types. This allows you to put media assets alongside documents and when you view the global browse-by-folder view you can see the related items grouped together.

Here is an example where it would make sense to group multiple collection type documents together:

Campaigns (top level folder)
└── Spring Launch 2025 (folder)
    ├── Fresh Start for Spring (post)
    ├── header-image.jpg (media)
    └── thumbnail-image.png (media)

Which one is better?

We are not sure one is better than the other, we think they both work well in different scenarios. It's when you combine something like the the users example with the posts example above where things start to get confusing.

It is currently possible to achieve this on some level.

1. You could create top level folders for each collection type or multiple collection types and then place them at the top level and then structure content within them.

├── Users (folder)
└── Media and Posts (folder)

2. You could add a new field to the folders collection using collectionOverrides and add a multi-select field that lists collection slugs. Once you have that you could add a baseListFilter to the folders collection and you could check the current route and optionally apply a filter similar to:

where: {
  collectionTypes: {
    in: [req.routeParams.collection]
  }
}

Note: There might be some nuances here that we would need to support, but in theory this should work!

With this approach you would also need to think about:

• Validation - so documents cannot be added to documents cannot be added that do not meet the collectionTypes criteria
• Folder default values - nested folders should inherit the settings of their parents as the default. i.e. a folder created inside of a posts only folder should also only allow posts
• What happens if you change the supported collectionTypes of a folder that already has documents within it?

Final question

Is this feature something that is common enough to:

• Be supported by a plugin?
• Built into core?
• Should we just provide an example and allow users to implement it themselves?

In closing, lets go back to the campaigns example above. A better folder structure might look like:

Campaigns (top level folder)
└── Spring Launch 2025 (folder)
    ├── Posts (folder)
    │   └── Fresh Start for Spring (post)
    └── Assets (folder)
        ├── header-image.jpg (media)
        └── thumbnail-image.png (media)

Where:

• Campaigns shows up in both posts and media collections
• Campaigns ➔ Spring Launch 2025 shows up in both posts and media collections
• Campaigns ➔ Spring Launch 2025 ➔ Posts only appears in the posts collection
• Campaigns ➔ Spring Launch 2025 ➔ Assets only shows up in the media collection

[codeflorist]

From my point if view, i would expect folders to be collection specific by default.

Global folders are something, i would call Tags.

So imho the best solution would be 2 separate features, that can exist next to each other:

• Folders, which are collection specific.
• Tags, which are global, and each document can also have multiple tags.

I think, this would be a clean and intuitive solution, since Folders and Tags would do ecactly, what one would expect from these terms.

This would also split the complexity of each usecase, improving testability and maintainability, instead of having one "god-feature".

My guess is also, that feature-requests for a neatly implemented tags-feature would arise sooner or later.

The clean separaration of the two now would catch two birds with one stone and be a long-lasting solution, that adhers to all thinkable usecases i guess.

But i guess this would go in a different direction, that you already took.

Regarding the stated questions: I would definitely put the folders (and tag) feature into the core. It's just what people expect to be part of a modern CMS.

[jmikrut]

It's possible that we can build a way to specify that folders are indeed collection-specific if that is what we hear is most widely expected. We could do that pretty easily.

But the big thing is that if we made folders collection-specific, they might only be able to be collection-specific and not have global folders at that point. Do you think you'd ever miss the ability to have global folders, like Google Drive? Or would you just opt into collection-specific folders and be happy from there?

You could, as you mentioned, build a system of "tags" using Payload as-is if you wanted a global system.

[codeflorist]

I'm rather new to Payload, but i guess that one could implement a tags functionality.

But to really neatly integrate the feature into the UI, i guess quite a bit of work would be necessary. So it would be great, if this feature came out of the box.

My guess is also, that feature-requests for a neatly implemented tags-feature would arise sooner or later.

The clean separaration of the two now would catch two birds with one stone and be a long-lasting solution, that adhers to all thinkable usecases i guess.

[bratvanov]

First off, thank you for all the hard work on shipping folders in Payload – this is a huge milestone!

I see the value in supporting global folders, especially for use cases like grouping related Posts and Media docs. However, I strongly believe that collection-specific folders should be the default, with global folders as an opt-in feature (this opinion is shared by many others based on the number of thumbs up on this issue).

This mirrors the UX patterns of major operating systems:

macOS Finder

Windows Explorer

PayloadCMS Admin Panel

All three UIs follow the same pattern: categories in the left sidebar (e.g. Documents/Pictures or Pages/Media), and files/folders on the right. In both OS examples, a folder created inside "Documents" doesn’t appear in "Pictures" — but in Payload, folders currently appear across all collections, which breaks this expectation and creates a jarring UX.

In OS environments, when folders span categories, it’s via shortcuts or symbolic links — not by default. Similarly, in Payload, I’d expect to create a folder under "Posts", then optionally drag it to "Media", where the UI could ask if I want to move it (keeping it collection-specific) or create a shortcut (which will basically be a reference/link to the original folder, but it will then be accessible from both collections – you can then slightly change the icon of the folder to signify that it's a shortcut/link).

This model of collection-specific first, shortcut/reference by choice is more realistic than global folders. Most folders make sense only in a single collection. Some will make sense across a few collections (via shortcuts/symlinks). Very few folders will make sense in every folder-enabled collection (truly global folders).

Regarding your questions:

• Plugin? No plugin, please.
• Built into core? Yes — this should be a native, first-class feature.
• Just provide an example? No — collection-specific folders should work out of the box, without custom code.

[jhb-dev]

First of all, thanks for opening this RFC and actively involving the community! I think it’s important to get this feature right before marking it as stable.

In my opinion, collection-specific folders should be the default, as they better reflect very common use cases like organizing media. Global folders can be valuable in some scenarios, but should remain an opt-in feature. Since folder handling is a fundamental part of the CMS experience, both modes should be built directly into the core of Payload, not implemented through an external plugin.

As for tags, they can be easily implemented on a project basis, so I don't see an immediate need for them to be part of the core.

[jhb-dev]

One additional thought: it might be worth considering how the current grouping mechanism for collections ties into this discussion.

For example, if I have multiple media related collections inside a 'Media' group (e.g. 'images' and 'videos'), with images hosted on S3 and videos on Mux, it would be very useful to enable folders specifically for these grouped collections. Having folder support scoped per group would offer flexibility for managing different storage backends and media types.

The folder view could be reflected visually in the admin sidebar, perhaps by displaying a folder icon next to the group name.

[JesperWe]

Here are my 2 cents: I believe this RFC exists because a lot of people, like myself, were taken by surprise by the global folder feature.

Why the surprise? Because (on top of what @bratvanov illustrates) most alternative headless data management tools implement folders as collection specific. And those "lots" of people are used to that, and was expecting that.

I can see the potential value of organizing documents of different types so that they can be accessed as defined set. But to me that solves use cases that are further from the core of what Payload is called upon to do.

So yes, I too support collection scoped folders as the default. The current implement will lead us down a long track of explaining again and again to users why they have to go through some (yet to be defined) hoops to arrive at the most commonly expected behavior.

[immotus]

It looks like my thoughts are largely consistent with those of others who chimed in. The current implementation of folders and the fact that they are indeed global are contradictory to the very concept of a folder. I understand the thinking behind the choice, but then they are not folders, and this is confusing. Folders, by their very definition, are structural elements that can be nested, have multiple children, but only one parent (or no parent for top-level folders). In the current implementation, they aren't folders, but rather tags, or labels, if drawing analogies with Google Drive or Gmail.

The summary of my suggestions

• Folders should be folders, i.e. structural constructs scoped to a particular collection.
• Introduce a tag/label concept to support the original thinking as outlined by @JarrodMFlesch. These might even be based on the underlying implementation of 'folders', but somehow flagged that they behave as labels and are globally scoped.
• Should be the core functionality. Each individual collection should define that it is using folders rather than a plugin-style globally defined folders config that lists the collections to be patched with folder support.
• UX improvements. Currently, in a media/upload collection, the presentation of the content in the collection is very different between when browsing By Folder → List View and All Media modes. In my opinion, the list view in By Folder mode should be identical to the All Media mode, i.e. with a thumbnail preview, column selector, and filtering.

Final question and Answers

• Be supported by a plugin? — No. It is such a central and ubiquitous concept that it deserves to be in the core.
• Built into core? — Yes. Absolutely Yes.
• Should we just provide an example and allow users to implement it themselves? — No. As above, it is such a ubiquitous concept that it should be as easily configurable as fields: [{ type: "text", name: "title" }].

[ChristopherLMiller]

The idea of global folders is well placed, but in terms of a CMS i think was misplaced as the 'standard' has been basically collection specific folders. I can see the appeal of being able to group things into those folders of various content types, but i think most users will probably not use it that way.

My opinion is that folders should the ability at the like app level to create group of folders, and then in the collection be able to specify what folder those can go into so that you can opt in to share between different collections.

[swheeler7]

I would echo a lot of the comments here in saying that my primary need for folders is for them to be collection specific. The main thing I would use folders for is to organize any uploaded files that are being stored on s3, and that is how I am currently using the folders feature as I am only using it for my upload enabled Media collection.

I understand the idea behind global folders, but taking the campaigns/launches example I personally would just use a campaigns collection and a launches collection with join/relationship fields on posts/media. The power of the join field/relationship field is amazing (especially the polymorphic joins, they feel like magic) and I would prefer to explicitely define the relationships in my schema. This approach also would give me better access control, validation, and hooks I can use. I know that the folders approach can eventually be improved to have those things as well, but seems like a lot of work to maintain two seperate content management strategies. Perhaps this is more a reflection of the org I work at or the people that I work with - but I have had to dig through too many unmaintained and unorganized google drive folders for me to want to implement a similar flow within payload. People will create temporary folders for last minute things, go on vacation, forget about why they created certain folders, or which version is the most updated, etc. In fact a huge motivating factor for me to start developing with payload was to get as far away from using google drive/google sheets to organize content as I could. Again, could just be an issue with the org I work at but I have seen enough problems with this approach (especially at scale) that going in this direction makes me nervous

So considering all that, my preference would be for folders to be collection specific. I think a lot of what is intended to be implemented by the global folders can be implemented with improvements to the relationship/join fields. I know this is beyond the scope of this RFC but I do want to share my thoughts for future improvements to the join field

• Alternate 'folder' appearance for join field: Just as the folder view is implemented as an alternate to the default list view, maybe the join field could have an alternate view that displays the joined content in a folder view.
• filtering joined content via WhereBuilder like the default list view
• alternate 'array' appearance for join field: The array field is great but hard to use with the local/rest api (especially when trying to update nested data). The join field could replace the array field and have an 'array' appearance

That all being said, I know every organization is different and maybe there is a desire/demand for global folders. My personal thought is that more value would be gained by focusing on improving the ui for the relational model as I think there is a ton of potential there. Thank you for considering our feedback, and I do want to really voice my appreciation of the effort that went into the folders feature. It's ambitious, and the UI so far feels amazing to use and is incredibly well thought-out. No matter what the final implementation ends up being I will be using the folders to organize my static content, but thank you for letting us be part of the process

[cgilly2fast]

I very much like the global folders setup, and hope the solution allows for devs to pick and chose their folder setup.

[mikecebul]

My use case would be connecting a collection "media" (images and PDFs) to another collection like "tournaments". If it's collection specific then I can just name a folder the same as a tournament title, then nest in folders for each year. Global currently would be a little confusing for editors with folders and collection lists. If there's a better way to use global folders so it's more intuitive I'm all for it.

Second I want folders for blocks. Then I don't have to worry about creating tons of specific blocks if I could organize them better.

[JarrodMFlesch]

Update, here is a draft PR that I have been working on to enable the requests in this thread!

I think what everyone here has voiced is abundantly clear. I think we can support global and scoping of folders on a per collection basis.

[oyatek]

Could you explain please, I just created a new account on Payload and I added "folders" to config:

folders: {
    debug: true, // optional
    collectionOverrides: [
      async ({ collection }) => {
        return collection
      },
    ], // optional
    fieldName: 'folder', // optional
    slug: 'payload-folders', // optional
  },

I'm using cloud Payload. After build I get this error:

./src/payload.config.ts:94:1
--
Type error: Object literal may only specify known properties, and 'folders' does not exist in type 'Config'.

[JarrodMFlesch]

What version are you on?

[oyatek]

It turned out the old version was installed even though it was stated as "latest" in packages.json. I updated, now the folders became available. Now there's a different issue. When I navigate to http://localhost:3000/admin/collections/posts/payload-folders - the page crashes and I get the following error:

⨯ TypeError: Cannot read properties of undefined (reading 'has')
    at has (../../../../src/elements/FolderView/FolderFileCard/index.tsx:154:46)
  152 |     <FolderFileCard
  153 |       className={className}
> 154 |       disabled={(isDragging && isSelected) || itemKeysToMove.has(item.itemKey)}
      |                                              ^
  155 |       id={item.value.id}
  156 |       isFocused={focusedRowIndex === index}
  157 |       isSelected={isSelected} {
  digest: '3990930435'
}
 GET /admin/collections/posts/payload-folders 500 in 1735ms

Am I doing something wrong?

[cgilly2fast]

I am having this same issue @oyatek

[mikeploythai]

@oyatek same here.