The @payloadcms/plugin-nested-docs package adds a self-referential parent field and a precomputed breadcrumbs array to any Payload collection, turning a flat page list into a real content hierarchy without writing a single recursive database query. I added it to a multi-tenant Payload project to support multi-segment URLs like /company/about/team, and the plugin handled the parent-child relationship, the breadcrumb trail, and the cascading updates when a parent page moves or gets renamed. Tested with Payload 3.88.0 and the plugin at the matching version, in a project running Next.js catch-all routing and localized content across English and French Canadian locales.
I hit this while building an informational site inside a multi-tenant Payload project. Pages had grown from a handful of top-level entries into nested sections with sub-pages several levels deep, and the flat pages collection had no way to represent that structure. Editors would have had to type full composite paths directly into a single slug field, which invites typos and breaks every child link the moment a parent page gets renamed. The official nested docs plugin solves the relationship and the breadcrumb trail out of the box. The one gap it leaves open in a multi-tenant setup is tenant isolation: its default parent-selection filter lets an editor pick a parent page from any tenant's site, which needs a custom fix before it's safe to ship. This guide walks through the plugin's mechanics, the exact configuration used in production, that tenant-scoped fix, and how the frontend resolves nested URLs from the precomputed breadcrumb data.
If you're setting up multi-tenancy from scratch first, my production-ready multi-tenant setup guide covers the routing and isolation groundwork this plugin builds on top of.
What the Nested Docs Plugin Actually Adds
The plugin is a first-party Payload package, maintained inside the official payloadcms/payload monorepo and published in lockstep with Payload core. Installing version 3.88.0 alongside Payload 3.88.0 keeps you on the same compatibility line the plugin was built and tested against.
Registering it on a collection adds two fields and two hooks:
A parent relationship field, capped at one level deep, positioned in the sidebar by default. Editors pick a single parent document from the same collection.
A breadcrumbs array field, marked read-only and localized, storing { doc, url, label } entries for every ancestor in the chain.
A beforeChange hook that walks up the parent chain and rebuilds the breadcrumb array whenever a document saves.
An afterChange hook that resaves every descendant when a parent's label or URL changes, so a rename propagates down the entire subtree automatically.
Two exported helpers do the field creation: createParentField(relationTo, overrides?) and createBreadcrumbsField(relationTo, overrides?). Both accept a Payload field config as an override, which is how the tenant-scoped filter later in this guide gets applied without forking the plugin.
One default worth knowing before you configure anything: the plugin does not generate URLs on its own. Without a generateURL callback, every breadcrumb entry saves with url: undefined. The label falls back to collection.admin.useAsTitle or the document ID, but the URL needs an explicit function.
collections scopes the plugin to pages only, so other collections in the project stay untouched. generateLabel pulls the document title for breadcrumb display text. generateURL reduces the full ancestor chain into a single path by concatenating each ancestor's slug, which is what produces /company/about/team from three separate documents.
Register the plugin in the project's plugin array before the multi-tenant plugin:
Order matters here because the multi-tenant plugin also modifies collection configs, and registering nested docs first keeps the field additions predictable when both plugins touch the same collection.
Restricting Parent Selection to a Single Tenant
The plugin's default parent filter only excludes the current document and prevents circular references. It has no concept of tenants, so without an override, an editor on Site A can select a page from Site B as a parent. That's a real content-isolation bug in any multi-tenant project, not a cosmetic issue: it lets cross-tenant relationships leak into the breadcrumb trail and the generated URL.
The fix overrides createParentField directly in the collection's field config:
filterOptions runs on the admin UI's parent picker and constrains the query Payload uses to populate the dropdown. Reading the current document's site relationship and adding it as an equals condition keeps the picker limited to pages that belong to the same tenant. The id: { not_equals: id } condition is preserved from the plugin's own default so a document still can't select itself as its own parent.
One TypeScript detail worth flagging: inline object literals inside filterOptions fail validation against Payload's Where type. Building the conditions as an explicitly typed Where[] array first, then spreading them into { and: andConditions }, is what satisfies the type checker here.
Resolving Nested URLs on the Frontend
With breadcrumbs precomputed at write time, the frontend query resolves a nested URL by matching against the breadcrumb array instead of running a recursive lookup at request time.
Matching on slug alone breaks for nested children, since a child page's own slug field only holds its own segment (team), not the full path (/company/about/team). The or clause checks breadcrumbs.url first, which holds the full computed path, and falls back to plain slug matching for top-level pages that have no breadcrumb trail yet. This is the query that lets a Next.js catch-all route resolve any depth of nesting against one collection without walking the tree at request time.
depth: 0 keeps the read fast, since the breadcrumb array already contains everything the page needs to render its own trail. There's no need to populate the full ancestor documents for a page view.
The breadcrumbs.length > 1 guard hides the whole trail on top-level pages, where a single-entry breadcrumb would just repeat the page title. Every non-final crumb renders as a link using the precomputed url, and the current page renders as plain text with aria-current="page" for screen readers. Nothing here queries the database again; the entire trail comes straight from the breadcrumbs field fetched in the page query above.
Handling Localized Nested URLs
Because the breadcrumbs field is localized, each locale carries its own set of translated labels and, more importantly, its own URLs when slugs differ by language. A language switcher that needs to jump to the equivalent page in another locale can pull the leaf breadcrumb entry, strip leading and trailing slashes, and reconstruct the locale-prefixed path from it. That's how a page like /en-CA/company/about resolves to /fr-CA/entreprise/a-propos without maintaining a separate slug-mapping table.
Nested Docs vs Hand-Rolled Recursion vs Flat Slugs
Approach
When to use
Trade-off
@payloadcms/plugin-nested-docs
Any Payload project needing multi-level page hierarchies with breadcrumbs
Write-time cost on deep trees when a parent renames, since every descendant resaves sequentially
Hand-rolled recursive queries at read time
Full custom control over the hierarchy logic is required
Adds database latency to every page load and requires building and maintaining the recursion, the cycle guards, and the localization handling yourself
Flat composite slugs typed manually
Very small, rarely-changing page sets
Prone to editor typos, no automatic breadcrumb labels, and a parent rename breaks every child link unless each one gets updated by hand
The plugin's tradeoff is a write-time one. Reads stay at O(1) against an indexed field, since the breadcrumb trail is already stored on the document. The cost shows up when a parent with many descendants gets renamed, since the afterChange hook triggers a sequential payload.update call for every child in the subtree.
FAQ
Does the nested docs plugin support localized breadcrumbs?
Yes. The breadcrumbs field ships with localized: true, so each locale stores its own translated labels and URLs. Language switchers can read the leaf entry for the active locale to build the equivalent path in another language.
What happens to child pages when I move or rename a parent?
The plugin's afterChange hook resaves every descendant automatically, recalculating their breadcrumb trails to match the new parent label or URL. On a deep tree, this runs as a sequence of individual update calls, so a rename on a page with dozens of descendants takes noticeably longer than a rename on a leaf page.
Can I use this plugin in a multi-tenant Payload setup?
Yes, but not safely with the default configuration. The plugin's built-in filterOptions only prevents self-selection and circular references. It has no tenant awareness, so a custom filterOptions override that constrains the parent picker to the current tenant is necessary before shipping.
Does the plugin generate page URLs automatically?
No. Without a generateURL callback in the plugin config, every breadcrumb entry saves with an undefined URL. The label falls back to the document's title or ID, but the path itself needs an explicit function that reduces the ancestor chain into a string.
How do I match incoming request URLs against nested pages?
Query against the breadcrumbs.url field in addition to the plain slug field. A child page's own slug only holds its final path segment, so matching on slug alone resolves top-level pages correctly but fails on anything nested.
Conclusion
A flat pages collection can't represent a multi-level content structure on its own, and hand-rolling the parent relationship, the breadcrumb computation, and the cascade updates is a meaningful amount of code to build and maintain. The official nested docs plugin covers all three out of the box, tested here against Payload 3.88.0 in a multi-tenant project with localized content. The one piece it doesn't handle for you is tenant isolation on the parent picker, which a short filterOptions override closes. Combined with a frontend query that matches against the precomputed breadcrumbs.url field, the result is multi-segment URL resolution without a single recursive database call at request time.
Let me know in the comments if you have questions, and subscribe for more practical development guides.
