[RFC] Tree View

[JarrodMFlesch]

The problem

Managing nested documents of any kind can be a bit tricky. Basically you set relationship field on a collection and call it "docParent". That relationTo on that field is set to the same collection where you added the field. That is all you really need to create a tree like structure in Payload.

Some use cases for this structure normally evolve into:

• creating nested slug and title like paths, useful for breadcrumbs and page slugs
• ordering nested documents
• managing these nested documents

The first one is probably the hardest one. Documents need to know when their parents change so they can update their slug and title paths, and that has to be done across all documents that rely on the document you are editing. You could be editing a parent document that has children with nested children. If you edit a field that is used to generate the slug, then all of those children need to know that they need to update their slugs and title paths. What if the title path is localized? Then it gets even more complex because now you need to update the localized document values for all those nested children.

Ordering nested documents can be done now that Payload supports ordering documents. However the difficulty comes when you are visually looking at the list view because you must know what order your docs are in when you are moving them around so they all stay in perfect order. It is not ideal for managing nested documents.

Also you might want to organize documents from many collections all based on a hierarchical structure, where you can easily browse through the hierarchy based on a given taxonomy. We have folders, but folders have a very important constraint: a given document can only be in a single folder. Let's say you want to organize by tag, and a document can have many tags. A tag sits in a hierarchy of other tags and you want to be able to easily browse them. We don't have a great UX to browse this type of structure right now.

Current solutions

Today, you might use something like the nested-docs plugin and that would be an "ok" solution.

A couple issues with the plugin:

• cannot localize slugs or labels out of the box
• it allows you to pass in your own generateURL and generateLabel functions which means the plugin must run every time the document is updated
• no visualization when managing documents

So what is this RFC for?

We have been working with a few customers in design to implement something along the lines of "Tree View", which would be a new way to view documents that shows hierarchy in a list view. The idea is to make managing nested documents more navigable and easier to understand at a glance.

Here is a simplified example for "nested pages":

Pages (collection)

├── Home
│
├── Used Vehicles
│   ├── Our Inventory
│   └── Pricing
│
├── New Vehicles
│   ├── Our Inventory
│   └── Pricing
│
├── About Us
│   ├── Our Team
│   │   ├── Leadership
│   │   └── Open Positions
│   └── Our History
│
├── Service
│   ├── Schedule Now
│   └── Pricing
│
└── Contact Us

And here is a simplified example for "nested tags":

Tags (collection)
├── ACME Motors
│   └── Year
│       ├── 2026
│       │   └── Vehicle
│       │       ├── Sedan
│       │       │   └── Package
│       │       │       ├── Base
│       │       │       ├── Premium
│       │       │       ├── Limited
│       │       │       └── Sport
│       │       ├── SUV
│       │       ├── Truck
│       │       └── Coupe
│       ├── 2025
│       └── 2025
└── Pinnacle Motors

This RFC is for a core feature, something that you could turn on a the collection level and it might look like:

export const TagsCollection = {
  slug: 'tags',
  treeView: true, // <-- new property
  fields : []
}

How might it look visually?

Pages Example

Tags Example

Tree View List Search

Ordering & Moving Tree View Documents

Implementing something like Tags w/ join

Questions to the community

• This is a new way to browse your collection documents. It's similar to folder view, but different. When we launch this, we'll have three different ways to navigate your documents (table, tree view, folder view). This likely necessitates some UX revisions to Payload in the longer-term as part of 4.0. What would you want to see here? This kind of overlaps with our UI evolution RFC!
• Would you use tree-view as the default navigational structure for certain collections?
• When viewing the tree, do you want to see other column data? Or do you just want to see the title of the document?

[janus-reith]

Would you use tree-view as the default navigational structure for certain collections?

Absolutely! Very much anticipating that feature.

I've built a tree view recently as well but went with a more traditional approach and made it a separate pane between sidebar and list view. One advantage was that it could stay open while editing a single page. On the other hand, on the list view you end up having two views.

page.tree.mp4

Not sure if there's much inspiration to take from it, but maybe a right click context menu could be interesting, or some other more touch-friendly way for various interactions with items in that tree view.

[sealan]

What would you want to see here?

• Per-collection control over which views are surfaced, plus the ability to specify a default view, so the UI opens in the mode that best fits that content (i.e. when I load "Pages" the default preference is Tree View, but List View is available). Also state persistence (i.e. when I reopen the page, it shows me the previous state)
• Built-in hierarchical ordering that matches Payload's orderable method but works per parent (fractional indexing + reparent aware endpoints).
• Easy way to hook into when branches move, making it easy to trigger downstream jobs (batch cache purge / revalidation rather than per page, static site rebuild...)
• Moving a branch shouldn't block on recomputing every descendant’s slug/breadcrumb synchronously. If it could be really clever about when to update, that would be great (e.g. the user goes crazy on reordering the tree)
• Localised slug/breadcrumb propagation so nested children stay accurate when parents move, especially for multi-locale sites.
• Accessible drag and drop (keyboard + screen reader cues).
• Bonus: After hitting "Create New", option to trigger some interstitial view for choosing the parent page that drops directly into the hierarchy where the user wants it.
• Bonus: Ability to specify Icons / components for elements in the tree (e.g. Home Page, Landing Page etc.)
• Bonus: View access rules (some users can't access the tree view) or good UX when a user attempts to reorg the tree but doesn't have access (for whatever reason).

Would you use tree-view as the default navigational structure for certain collections?

• Yes! e.g. Pages Tree View (with List View still available for bulk edits or searching etc.)

When viewing the tree, do you want to see other column data? Or do you just want to see the title of the document?

• Title + status badges e.g. draft/published state, scheduled publish / visibility toggles.

Above is all based on some of the challenges I've encountered building a custom Tree View using the Nested Plugin, a custom fractional indexing (as the core only handles flat structures / doesn't handle reparenting). It works, but I'd rather have this in core / not maintain it :)

[saskia-compono]

> Would you use tree-view as the default navigational structure for certain collections?
Yes, this would really help for our Pages, Competency Framework and Tags collections to name a few

[saskia-compono]

What would you want to see here?

• Clean visual hierarchical structure with a familiar experience for users

• Options to easily expand and collapse the tree

• Options to promote, demote, move or add another document

When viewing the tree, do you want to see other column data? Or do you just want to see the title of the document?

• In certain instances it would be good to be able to include contents from a contextual field like Description as well but in a subtle way
• Option to show each document's publishing status
• An option to switch between 'clean' and more detailed view

[jhb-dev]

Thanks a lot for opening this RFC to the community, I think a tree view is an essential feature when using Payload for websites.

Regarding the challenge of updating all child documents when a parent changes, I’d like to share an approach that I’ve been using successfully in production almost a year now across multiple websites:

• Each document has a parent relationship field and a slug text field.
• Fields like path, breadcrumbs, and alternatePaths are virtual fields, generated on the fly based on the parent document and the slug.

The big advantage is that no cascading updates are required when a parent changes. All paths and breadcrumbs remain correct at all times because they are derived dynamically.

By making the parent field polymorphic (allowing parents from different collections), I was also able to build complex hierarchical structures across multiple collections, for example:

Pages Collection

• Frontpage (path: /)
• Countries (path: /countries)

Countries Collection

• Germany (path: /countries/germany)
• Netherlands (path: /countries/netherlands)

Regions Collection

• Rhineland-Palatinate (path: /countries/germany/rhineland-palatinate)
• Holland (path: /countries/netherlands/holland)

I’ve encapsulated this logic in a plugin: https://github.com/jhb-software/payload-plugins/tree/main/pages

---

I do have a couple of questions regarding the RFC:

1. Is the tree view intended to replace the nested-docs plugin?
2. Will it be possible to use the tree view purely as a UI layer for managing parent/child relationships, while keeping full control over path/breadcrumb generation for example with the approach above?
3. Will it be possible to view documents nested across multiple collections?