Nested Docs Plugin
This plugin allows you to easily nest the documents of your application inside of one another. It does so by adding a
new parent
field onto each of your documents that, when selected, attaches itself to the parent's tree. When you edit
the great-great-grandparent of a document, for instance, all of its descendants are recursively updated. This is an
extremely powerful way of achieving hierarchy within a collection, such as parent/child relationship between pages.
Documents also receive a new breadcrumbs
field. Once a parent is assigned, these breadcrumbs are populated based on
each ancestor up the tree. Breadcrumbs allow you to dynamically generate labels and URLs based on the document's
position in the hierarchy. Even if the slug of a parent document changes, or the entire tree is nested another level
deep, changes will cascade down the entire tree and all breadcrumbs will reflect those changes.
With this pattern you can perform whatever side-effects your applications needs on even the most deeply nested
documents. For example, you could easily add a custom fullTitle
field onto each document and inject the parent's title
onto it, such as "Parent Title > Child Title". This would allow you to then perform searches and filters based on that
field instead of the original title. This is especially useful if you happen to have two documents with identical titles
but different parents.
Core features
- Automatically adds a
parent
relationship field to each document - Allows for parent/child relationships between documents within the same collection
- Recursively updates all descendants when a parent is changed
- Automatically populates a
breadcrumbs
field with all ancestors up the tree - Dynamically generate labels and URLs for each breadcrumb
- Supports localization
Installation
Install the plugin using any JavaScript package manager like Yarn, NPM, or PNPM:
Basic Usage
In the plugins
array of your Payload Config, call the plugin
with options:
Fields
Parent
The parent
relationship field is automatically added to every document which allows editors to choose another document
from the same collection to act as the direct parent.
Breadcrumbs
The breadcrumbs
field is an array which dynamically populates all parent relationships of a document up to the top
level and stores the following fields.
Field | Description |
---|---|
label | The label of the breadcrumb. This field is automatically set to either the collection.admin.useAsTitle (if defined) or is set to the ID of the document. You can also dynamically define the label by passing a function to the options property of generateLabel . |
url | The URL of the breadcrumb. By default, this field is undefined. You can manually define this field by passing a property called function to the plugin options property of generateURL . |
Options
collections
An array of collections slugs to enable nested docs.
generateLabel
Each breadcrumb
has a required label
field. By default, its value will be set to the collection's admin.useAsTitle
or fallback the the ID
of the document.
You can also pass a function to dynamically set the label
of your breadcrumb.
The function takes two arguments and returns a string:
Argument | Type | Description |
---|---|---|
docs | Array | An array of the breadcrumbs up to that point |
doc | Object | The current document being edited |
generateURL
A function that allows you to dynamically generate each breadcrumb url
. Each breadcrumb
has an optional url
field
which is undefined by default. For example, you might want to format a full URL to contain all breadcrumbs up to
that point, like /about-us/company/our-team
.
Argument | Type | Description |
---|---|---|
docs | Array | An array of the breadcrumbs up to that point |
doc | Object | The current document being edited |
parentFieldSlug
When defined, the parent
field will not be provided for you automatically, and instead, expects you to add your
own parent
field to each collection manually. This gives you complete control over where you put the field in your
admin dashboard, etc. Set this property to the name
of your custom field.
breadcrumbsFieldSlug
When defined, the breadcrumbs
field will not be provided for you, and instead, expects you to add your
own breadcrumbs
field to each collection manually. Set this property to the name
of your custom field.
Overrides
You can also extend the built-in parent
and breadcrumbs
fields per collection by using the createParentField
and createBreadcrumbField
methods. They will merge your customizations overtop the plugin's base field configurations.
Localization
This plugin supports localization by default. If the localization
property is set in your Payload Config,
the breadcrumbs
field is automatically localized. For more details on how localization works in Payload, see
the Localization docs.
TypeScript
All types can be directly imported:
Examples
The Examples Directory contains an official Nested Docs Plugin Example which demonstrates exactly how to configure this plugin in Payload and implement it on your front-end. The Templates Directory also contains an official Website Template and E-commerce Template, both of which use this plugin.