RFC: Templates API for content

[paulpopus]

RFC: Templates API

TL;DR

Add a first-class Templates API to Payload core that lets editors save the data of any document, block, or field as a reusable template, and pre-fill new content from it. Same primitive at three levels: collection documents, blocks, and field values. Designed to extend later into a richer reusable-content / shared-content system.

---

The problem

Editors using Payload to build content-heavy products — articles, landing pages, marketing sites, ecommerce listings, knowledge bases — almost always end up repeating the same structures over and over. A "Recipe" article has the same hero, ingredients block, steps block. A "Case Study" page has the same intro, quote, two-column layout, CTA. A "Product" page has the same gallery → spec sheet → related-products composition.

Today, the workflows for "I want to start from a known structure" all have sharp edges:

• Duplicate a document. Clutters the list, requires renaming, breaks unique fields, and doesn't generalise to "I just want this block layout".
• Copy / paste blocks via the row clipboard. Works for one editor in one tab, doesn't survive a refresh, can't be shared with a teammate, can't be curated.
• Roll your own. Every team builds a one-off "templates" collection, a one-off seed script, a one-off pre-fill button. We've watched dozens of community projects do this from scratch.
• Default values in the config. Field defaultValue is static and lives in code — non-technical editors can't define or change it.

There is no Payload-native way to say "this exact configuration of fields/blocks is a starting point I want to reuse" — at the document level, at the block level, or at the field level.

Why we should care

This is one of the most-requested capabilities we hear from production teams. It comes up in:

• Agency conversations (clients want editors to ship pages faster without engineering involvement)
• Marketing-site customers (campaign pages share 80% of their structure)
• Ecommerce builds (product variants and PDPs are templated by category)
• Documentation/knowledge bases (article archetypes)
• Plain old support threads and Discord questions: "how do I let my editors create from a template?"

Every other block-based CMS in the space — Sanity, Storyblok, Contentful, Webflow CMS, Notion, Framer — exposes some version of this primitive. They build it themselves when we don't ship it. We can do it better than the per-project versions, in core, in a way that composes with the rest of Payload.

It's also the natural foundation for the reusable-content story we want to tell longer-term (see Future direction).

---

Proposal

Mental model

A template is a named, saved value that can seed an entity. Three entity tiers, increasing in granularity:

Tier	Entity	Saves…	Used to…
1	Collection document	The document's data	Pre-fill a newly created document in that collection
2	Block	A single block instance's data	Insert a pre-filled block into a blocks field
3	Field value	The full value of a field	Replace/seed a field's value (initially array and blocks; extensible to any field)

All three tiers share one storage collection, one config surface, one set of hooks, and one set of UI primitives. Adding a new tier later (e.g. groups, rich text trees) is purely additive.

Naming — open question

We're calling this "Templates" in the RFC because that's the term users already use when they ask for it. It does conflict with the existing templates/ folder in the repo (which is project starters, unrelated). We'd love feedback on alternatives — possibilities that came up:

• Presets — neutral, no conflict, lighter connotation
• Starters — same conflict with project starters, possibly worse
• Snippets — feels right for blocks, weaker for whole documents
• Patterns — used by some design systems; a touch abstract

A clean name matters more once this becomes the foundation for reusable content (where "templates" and "library" start meaning different things). Calling this out early so we can land on a name we won't regret.

Storage: payload-templates

A new internal collection following the payload-* convention used by payload-preferences, payload-locked-documents, payload-jobs, etc. — admin.hidden: true by default, fully extensible (hooks, access, custom admin components) like any other collection.

{
  slug: 'payload-templates',
  fields: [
    { name: 'title', type: 'text', required: true },
    {
      name: 'entityType',
      type: 'select',
      options: ['collection', 'block', 'field'],
      required: true,
    },
    // For 'collection': the collection slug.
    // For 'block':      the block slug.
    // For 'field':      the field's dot-path including its host collection (e.g. 'articles.layout').
    { name: 'entitySlug', type: 'text', required: true },
    // The saved value. JSON keeps us schema-agnostic across collections, blocks, and field shapes.
    { name: 'data', type: 'json', required: true },
    // Optional metadata
    { name: 'description', type: 'textarea' },
    { name: 'createdBy', type: 'relationship', relationTo: 'users' },
    // (timestamps via standard collection options)
  ],
}

Why a single JSON field rather than per-collection typed templates: templates need to span heterogeneous shapes (a Page template and an Article template have nothing structurally in common), and field/block templates store fragments rather than full docs. JSON keeps the storage trivial; validation and typing happen at apply time, where the target collection's schema is the source of truth.

Config surface

Templates are opt-in per collection — same shape as versions / upload / auth:

// payload.config.ts
{
  collections: [
    {
      slug: 'articles',
      templates: true,                // shorthand: enable everything
      // or granular:
      templates: {
        save: true,                   // expose "Save as Template" in the doc edit view
        create: true,                 // expose "Create from Template" in the list view
        access: { /* standard Access funcs */ },
      },
      fields: [
        // Field-level opt-in for tier 3 (initially blocks + array only)
        {
          name: 'layout',
          type: 'blocks',
          blocks: [...],
          templates: true,
        },
      ],
    },
  ],
}

Block-level opt-in (tier 2) is implicit: if a blocks field has templates: true, every block type inside it can be saved/inserted as a template. (We can add a per-block-type opt-out if there's demand.)

Apply semantics

Applying a template is a merge with the same lifecycle as duplicateFromID in the existing create operation. Concretely:

• Field defaultValues resolve first.
• Template data overlays on top of those defaults.
• User-provided data (from the form / API caller) overlays on top of the template.
• All beforeValidate / field hooks then run as normal.

This ordering matters: the user is always in control, and field-level defaults still apply for anything the template doesn't touch.

For tier 1 (collections), the apply path piggybacks on the existing duplicateFromID plumbing in create.ts — we add a sibling templateID parameter that sources from payload-templates instead of from a sibling document.

For tier 2/3, the merge happens client-side in the form state (the same place "duplicate row" already produces a new row).

UI integration

Tier 1 — collection list view. The existing "Create New" button (ListCreateNewDocButton) becomes a split-button when templates.create is enabled: primary action stays "Create New"; the chevron opens a list of available templates plus a "Manage templates" link. The doc edit view gains a "Save as Template" action in the document header menu when templates.save is enabled.

Tier 2 / Tier 3 — blocks and array fields. Both share a single integration point: the existing ArrayAction row menu (the popover behind the … icon on every block/array row). Two new items: "Save as Template" and "Insert from Template". Because both Blocks and Array already render through ArrayAction, this is one change with two-tier reach. Tier 3 (whole-field replacement) shows up at the field-header level rather than the row level.

Selection UI. A "Choose template" drawer that mirrors the existing block-picker (BlockSelector) — searchable, groupable by category, thumbnailable down the road. Filters automatically by entityType + entitySlug so a posts editor only sees posts templates, an "image-gallery" block only sees "image-gallery" templates, etc.

Access and permissions

Default rule: if you can create in collection X, you can use templates for collection X. Same idea for blocks/fields nested inside X. Saving a new template requires create-permission on payload-templates (default: same condition).

payload-templates exposes the standard access API like any other collection, so teams can layer on whatever they need: per-team scoping, "personal vs shared" scoping, role-based visibility, lock-down for non-editors, etc. The collection's hooks and admin components are also extensible — we explicitly inherit the same extensibility surface that payload-jobs and payload-query-presets already prove out.

---

Open design questions (the discussion part)

These are the calls we'd most like community input on before locking the design.

1. Naming. Templates vs Presets vs Snippets vs something else (see above).
2. Personal vs shared scope. Should templates default to personal (only the creating user sees them) with explicit sharing, or default to shared (anyone who can create in the collection sees them) with personal as opt-in? Other CMSes split on this.
3. Versioning / drafts on payload-templates. Probably yes — Payload's drafts machinery is right there, and templates evolve. Worth confirming.
4. Localisation. A template authored in en applied to a de document — copy the en data verbatim, leave fields blank, or refuse? Tentative answer: copy verbatim and let the editor translate; flag in the UI.
5. Uploads, relationships, IDs inside template data. Default to copying the references as-is (templates point to the same uploads/relations) vs. cloning. Probably reference-by-default for simplicity, with a beforeApplyTemplate hook for cases that need cloning.
6. Field-level vs collection-level opt-in for blocks/arrays. Is collection-level templates: true enough to enable Tier 2/3 inside that collection's blocks/array fields, or should each field opt in individually? Tentative answer: collection-level enables everything; per-field templates: false opts out.
7. Naming collision with payload-query-presets. If we end up calling this "Presets", there's already a presets collection for list-view queries. Either we rename one, or we pick a name that doesn't collide.
8. Block-type whitelisting on a template's apply target. When inserting a block template into a blocks field whose schema doesn't include that block type, do we silently skip, hard-error, or coerce? Probably hard-error.

---

Future direction (out of scope for v1)

The shape above is deliberately compatible with two follow-on capabilities we want to keep the door open for:

• Reusable / referenced content. Templates copy data. The same payload-templates collection (or whatever we end up calling it) can grow a mode: 'snapshot' | 'reference' field. In reference mode, the consuming document stores a pointer to the template, and edits to the template propagate to every reference. This is the headline ask behind "global blocks" / "shared content" / "reusable sections" — and it's a natural Tier 4 on the same primitive.
• Block libraries. Once Tier 2 templates exist, the path to a curated, themeable, project-level block library (with thumbnails, descriptions, categorisation) is a UI layer over the same data. No further core work needed.

We are not committing to either of these in v1. The v1 surface is small, additive, and shippable on its own. We're calling out the trajectory so reviewers can pressure-test the proposed shape against where it's headed.

---

What we're asking for in this discussion

• Reactions to the three-tier model — does collection / block / field cover the cases you actually want, or is something missing (rich text trees, group fields, relationships)?
• Strong opinions on naming.
• Feedback on the scope / permissions defaults (personal vs shared).
• Concrete user stories where the proposed apply-semantics (defaults → template → user-provided) would not do the right thing.
• A vote, basically: do we ship this in core, or is it better as an official plugin?

[HarleySalas]

I think it should be called templates anyway, despite the naming conflict.