[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?

[JarrodMFlesch]

@jhb-dev I think I have come to the same conclusion as you, I think paths have to be derived dynamically. The cascading updates is one thing, but as soon as drafts are introduced it is impossible.

If you were to draft a parent doc change where you moved its location, it would cascade to children and need to create draft entries. So in this case you would have 2 problems:

• this could create a lot of draft documents
• if you publish one of the children docs before the parent then you are in a bad place, with a path that is not published.

So yeah, I think dynamically is the likely the only way this would work. Which has its tradeoffs. The couple that come to mind are:

• not being able to search on paths
• the ability to search (efficiently) for scoped results. As in "match the search string but only for children of category A" since every doc only knows about its own parent. So you will need to waterfall request children for their parent fields. And you cannot store a parentTree because it would have the same draft problem noted above.

I'll have to check out your plugin and see if anything differs from what I have got so far.

[jhb-dev]

Hi @JarrodMFlesch glad to hear you came to the same conclusion. I have been using this virtual path field approach for quite some time now across multiple projects in production, and I believe it is the best approach.

You are right about the trade-offs. For search, this is not a major issue for me, since you can still query at the database level using the slug and then compare the paths at the application level.

Of course, this approach requires additional database requests to fetch the ancestors in order to construct the path. I saw in your draft PR that you are using a caching mechanism for this, which is great. My plugin does not include this.

What I find important is that the virtual path field is only computed when it is actually needed (selected). In my plugin, I handle this by inspecting the select object and only calling the function that generates the virtual fields when those fields are explicitly selected. This also requires extending the select object when, for example, only the path is selected, since the slug and parent fields are required to construct the path.

However, in the plugin context, I am somewhat limited by the current capabilities that Payload exposes. Because of that, it would be great if Payload provided a built-in mechanism to conditionally select dependent fields, as described in this feature idea: #14468

If you have an early draft version of the hierarchy feature ready to test, feel free to ping me so I can test it in my projects. I would be happy to migrate from my plugin to the built-in feature at some point 🙂

[dainmik]

This is a really great and desired feature, thanks for working on it.

The biggest issue with the nested-docs plugin for my use-case was that nested-docs didn't allow for parent/child relationships between documents within different collections.

@jhb-dev described several examples how they built complex hierarchical structures across multiple collections by making the parent field polymorphic. For my use-case, I have Content, Aggregate, and Series collections. Aggregate collection holds an array of Content and Aggregate entries, and the Series collection holds only Aggregate entries. Having these relationships displayed in tree view and having an ability to rearrange and drag-and-drop these entries from one collection to another would be extremely useful.

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

Yes, especially if the tree view would allow viewing and rearranging documents nested across multiple collections. In my described use-case, I would set the Series and Aggregate collections to always be displayed in tree view.

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

It would be helpful to be able to see other column data as well. E.g., if a collection defined a priority field, it could influence how a user might want to rearrange the items.

[MurzNN]

Yes, the limitation of using different collections is a blocker for me too! A simple example can be Categories + Products collections and a slug like /catalog-main-page-slug/main-category-slug/sub-category-slug/product-slug. I posted a separate question about this here #16324 - maybe we will find a solution there.

[JarrodMFlesch]

Update, working through extending payload core to support a sidebar navigation where things like hierarchical trees could live. But tabs could also be registered by users or other plugins and render other things in the sidebar.

PR here: #15470

[janus-reith]

Awesome!

[kresogalic8]

@JarrodMFlesch whats the status of tree view? when can we expect it delivered?

[CarloBu]

@kresogalic8, @jhb-dev, @saskia-compono, For me as well, the lack of a proper page-tree UI was the biggest drawback for my clients, so I couldn’t wait - I had to built a companion plugin for the nested-docs plugin. I intentionally didn’t touch any routing logic; it’s purely a UX/UI layer, the companion plugin only updates the parent field on move.. Everything else, like breadcrumbs/url/path generation, or how the frontend resolves routes, is the @payloadcms/plugin-nested-docs plugin's responsibility. I also aimed to preserve Payload’s existing filtering, search functionality, and official design language.

In my view, this is how the Payload page-tree UX/UI should have been from the start. The badges are easily customizable to match your preferred published/published-with-unpublished-changes/draft naming and color scheme.

I’m currently using it with my clients, so the plugin will continue to be developed and maintained to support the nested-docs page-tree UX/UI until the Payload team provides a better solution.

the plugin:

Page tree plugin repository:
https://github.com/WLF-Studios/payload-nested-docs-page-tree

[MurzNN]

By the way, about translations - found this thread https://payloadcms.com/community-help/discord/breadcrumbs-is-not-multilingual which describes that localization is supported:

Looking at the source code now, you shouldn't have to create your own breadcrumbs field here, instead you can set localization: true on your plugin config and the supplied breadcrumbs field will automatically be localized just as you have: https://github.com/payloadcms/plugin-nested-docs/blob/main/src/index.ts#L25

But I don't see the localization: true in the plugin configuration type 😕

[royalswe]

Awesome work! I will try it right a way 🎉

[CarloBu]

@MurzNN, sorry - my plugin is strictly a UI companion for the plugin-nested-docs plugin. I intentionally don’t touch breadcrumbs, URL, or path logic.

I hope the Payload team will soon expand the missing capabilities of the page tree plugin

[CarloBu]

I added new features to the page tree plugin:

• now users can reorder items in page tree view when orderable is enabled
• homepage now has home icon

heads up:
I changed the plugin name from plugin-nested-docs-page-tree to the payload-nested-docs-page-tree

https://github.com/WLF-Studios/payload-nested-docs-page-tree

[CarloBu]

Added pageTreeMoveContextKey in v1.2.3 to support SSG builds and prevent unnecessary page-tree move publish triggers.
https://github.com/WLF-Studios/payload-nested-docs-page-tree/releases/tag/v1.2.3