Open-source Payload block registry
Install Payload blocks wired, not pasted.
One command installs the block, wires it into Payload, and lands a reviewable git diff.
npx payload-components add hero-basicInstall replay — real output
payload-components installPayload-aware wiring
Command line
Install hero-basic with its wiring
$ npx payload-components add hero-basicpayload-components: installing "hero-basic" into ./acme-siteresolved hero-basic@0.1.0 · payload-website-startercopied 3 block source files into src/blocks/payload-components: installed "hero-basic" successfully.registered block in src/collections/Pages/index.ts
wired render mapping in src/blocks/RenderBlocks.tsx
ran payload generate:types
ran payload generate:importmap
The block, rendered
Hero Basic
Hero section · live in Payload, sample content
Files the install wrote
src/blocks/shared/heroFields.ts
src/blocks/HeroBasic/config.ts
src/blocks/HeroBasic/Component.tsx
src/payload-types.ts — regenerated
admin importMap.js — regenerated
Installs into the stack you already run
- Payload CMSv3
- Next.js15 / 16
- shadcnregistry
- Tailwindv4
- TypeScriptstrict
The install boundary
A block isn't live until it's wired.
Copying the files is the easy part — the four edits after are where every block, every repo, loses the day.
source: payload-components/manifests/hero-basic.jsonOne command
5 of 5 in one pass — reviewed as one git diff.
Block source
Collection schema
Render mapping
Generated types
Admin import map
A plain paste lands the block source. payload-components wires the other four.
Artifact
$ npx shadcn add hero$ npx payload-components add hero-basicBlock source
src/blocks/{shared/heroFields.ts, HeroBasic/config.ts, HeroBasic/Component.tsx}shadcn addcopiedpayload-components addcopiedCollection schema
src/collections/Pages/index.tsshadcn addleft to youpayload-components addpatchedRender mapping
src/blocks/RenderBlocks.tsxshadcn addleft to youpayload-components addpatchedGenerated types
src/payload-types.tsshadcn addleft to youpayload-components addregeneratedAdmin import map
admin importMap.jsshadcn addleft to youpayload-components addregenerated1 of 5 artifacts. The rest is your TODO list.
5 of 5 in one pass — reviewed as one git diff.
MIT licensed, end to endIntegration and e2e suites gate every PRNightly fresh-repo install smoke testPayload 3 · Next 15 / 16Open registry JSON at /r/registry.json
Workflow
From catalog to commit in three moves.
No scaffolds, no lock-in — plain source plus two scoped patches you can read.
- 01
Read the contract
Fields, files, and patches — before you run anything.
/components - 02
Run one command
The CLI checks your project, then wires it in one pass.
npx payload-components add hero-basic - 03
Commit a working block
Source, two patches, regenerated types — reviewed like any PR.
git diff --stat
Rendered from source
The catalog
The catalog, rendered live.
No screenshots — each specimen is the real component, rendered from source.
payload-components/source/blocks/FeatureGridBasic/Component.tsxRendered from component source · sample contentnpx payload-components add feature-grid-basic installs the schema, this component, and the wiring between them.eyebrowtitledescriptionitems[] · 3–6links[]Page blocks
InstallableBlocks for the Pages layout builder — installed with full wiring: collection config, render mapping, generated types, import map.
FAQ
Questions, answered straight.
The short version of the docs. Every answer links back to something you can verify in the repository.
Is Payload Components free?
Yes — and built to stay that way. The registry, the CLI, both components, and this site are one MIT-licensed repository: no pricing, no license key, no gated tier. Payload Components is community-first by design — the catalog grows from real installs and contributions, not a paid roadmap.
What is a Payload CMS block?
In Payload, a block is a composable page-builder field — a reusable content section (hero, feature grid, CTA) editors stack to lay out a page. Payload Components ships pre-built blocks plus the wiring that makes them live, so a block is not just copied in: it is registered in your Pages collection, mapped in your renderer, typed, and added to the admin import map.
How do I add a hero block to Payload CMS?
Install one with the CLI — `npx payload-components add hero-basic`. It copies the block source into your project and wires it end to end: registers it in your Pages collection, maps it in RenderBlocks, and regenerates your Payload types and admin import map — landing as one reviewable git diff. The same command adds any block in the catalog.
What exactly does an install change in my repo?
Three things: component source files are copied in (block config, component, shared utilities), exactly two files are patched (your Pages collection and RenderBlocks.tsx — each component manifest declares them), and Payload regenerates its own output (payload-types.ts and the admin import map). All of it shows up as an ordinary git diff.
What happens if I run the same install twice?
It converges. The CLI detects existing wiring and skips it — the real output is payload-components: "hero-basic" is already installed. Install state is recorded in .payload-components/state.json, so partial installs are visible and recoverable instead of silently broken.
Which projects are supported today?
Payload v3 + Next.js 15/16 projects shaped like the official website starter — rendering layout blocks through src/blocks/RenderBlocks.tsx and registering page blocks in src/collections/Pages/index.ts. The CLI checks your project against the published support matrix before touching anything.
Why not just run npx shadcn add?
A plain shadcn install copies files and stops. Payload blocks only work after they are registered in your collection schema, mapped in your renderer, typed, and added to the admin import map. payload-components wraps the same registry delivery with exactly that wiring — that boundary is the product, and the wiring ledger above shows it row by row.
How do new components get into the catalog?
Deliberately. A component lands only when its source, manifest metadata, docs page, and installer test coverage ship together — half-wired blocks never reach the catalog. Propose the next component in a GitHub issue; the catalog grows from real installs.
This section is one of our blocksnpx payload-components add faq-accordion
Open source
Open source, end to end.
The registry, the CLI, the components, and this site are one MIT-licensed repository. Read the installer before you trust it — that is the point.
npx payload-components add hero-basicI built payload-components because installing a Payload block was never the copy-paste — it was the four edits after. The CLI exists so the second project, and the tenth, get that wiring for free. Read the installer source before you trust it; shipping it MIT is the point.
DucksssMaintainer, Payload Components