# Payload Components

> Payload Components is an MIT registry and CLI that installs typed Payload CMS blocks into Payload v3 + Next.js projects with config, render maps, types, and import maps wired.

Payload Components is an open-source (MIT) registry and CLI for Payload CMS v3 + Next.js.
Running `npx payload-components add hero-basic` copies a block's source, registers it in your
Pages collection, maps the renderer, and regenerates Payload types and the admin
import map — landing as one reviewable git diff rather than a manual checklist.
Docs runtime: Fumadocs-powered Next.js site.

## Primary links
- [Home](https://www.payload-components.xyz/)
- [Docs](https://www.payload-components.xyz/docs)
- [Component catalog](https://www.payload-components.xyz/components)
- [About](https://www.payload-components.xyz/about)
- [Public registry](https://www.payload-components.xyz/r/registry.json)
- [Full LLM context](https://www.payload-components.xyz/llms-full.txt)
- [GitHub repository](https://github.com/Ducksss/payload-components)

## Supported stack
- Payload CMS (v3)
- Next.js (15 / 16)
- shadcn (registry)
- Tailwind (v4)
- TypeScript (strict)

## Installable components
- Hero Basic: npx payload-components add hero-basic — A headline-led marketing hero with CTA links, proof badges, Payload block config, and frontend rendering.
- Feature Grid Basic: npx payload-components add feature-grid-basic — A text-first feature grid with repeatable items, optional CTA wiring, and idempotent registration.
- Feature Split: npx payload-components add feature-split — A two-column feature section pairing a heading and CTA with a stacked feature list.
- Feature Bento: npx payload-components add feature-bento — An asymmetric bento grid that leads with a featured cell and fills supporting cells.
- Feature Steps: npx payload-components add feature-steps — A numbered steps block for sequential, how-it-works feature flows.
- Embed Basic: npx payload-components add embed-basic — A responsive, sandboxed iframe block for approved HTTPS embeds with a selectable aspect ratio.
- Logo Cloud Grid: npx payload-components add logo-cloud-grid — A centered, wrapping wall of editable logo uploads under a heading, installed as a wired Payload block.
- Logo Cloud Hover: npx payload-components add logo-cloud-hover — A logo wall that dims and blurs on hover to reveal a single call-to-action.
- Logo Cloud Marquee: npx payload-components add logo-cloud-marquee — An auto-scrolling marquee of editable logos with progressive-blur edge fades.
- Logo Cloud Inline: npx payload-components add logo-cloud-inline — A compact label-over-logos strip for editable trust logos.
- Logo Cloud Inline Wrap: npx payload-components add logo-cloud-inline-wrap — A single wrapping row that keeps the label inline with editable trust logos.
- Content Columns: npx payload-components add content-columns — A two-column content section pairing a heading with body paragraphs and a CTA, installed as a wired Payload block.
- Content Image Lead: npx payload-components add content-image-lead — A content section led by a full-width image above a two-column heading, body, and CTA.
- Content Feature Media: npx payload-components add content-feature-media — A content section pairing body copy and two icon features beside a framed media panel.
- Content Feature Split: npx payload-components add content-feature-split — A content section pairing a side media panel with body copy and two icon features.
- Content Showcase: npx payload-components add content-showcase — A centered content section with an intro, a full-width image, and a four-up grid of icon features.
- Content Quote: npx payload-components add content-quote — A content section pairing a media panel with body copy and a cited pull quote.
- Content Community: npx payload-components add content-community — A centered content section with a heading, body copy, and a wall of community avatars.
- Content Split Rows: npx payload-components add content-split-rows — A content section with an intro and alternating media-and-text rows.
- Content Rows: npx payload-components add content-rows — A content section with an intro and a uniform stack of media-and-text rows.
- Content Image Frame: npx payload-components add content-image-frame — A centered content section with an intro and a layered, framed screenshot.
- Content Stats: npx payload-components add content-stats — A content section with an intro, a grid of icon features, and a stats list.
- Content List: npx payload-components add content-list — A serif-headed content section pairing a heading with a labeled-term list.
- Content List Columns: npx payload-components add content-list-columns — A serif-headed content section with a two-column labeled-term list.
- Content List Icons: npx payload-components add content-list-icons — A serif-headed content section with an intro and a multi-column icon list.
- Integration Grid: npx payload-components add integration-grid — A responsive grid of integration cards — logo, name, description, and a learn-more link — installed as a wired Payload block.
- Integration Cluster: npx payload-components add integration-cluster — A centered cluster of integration logos around a featured brand mark, with a heading and CTA.
- Integration Split: npx payload-components add integration-split — A two-column section pairing a featured-mark logo cluster with a heading, subtext, and CTA.
- Integration Connect: npx payload-components add integration-connect — Integration logos wired to a central brand mark by connector lines, installed as a wired Payload block.
- Integration Orbit: npx payload-components add integration-orbit — Concentric rings of integration logos that orbit a featured brand mark on hover.
- Integration List: npx payload-components add integration-list — A vertical list of integration rows — logo, name, description, and an add action — installed as a wired Payload block.
- Integration Marquee: npx payload-components add integration-marquee — Three auto-scrolling rows of integration logos around a featured brand mark, with progressive edge fades.
- Integration Testimonial: npx payload-components add integration-testimonial — A two-column section pairing a customer quote with a grid of integration logo cards.
- Call To Action Centered: npx payload-components add call-to-action-centered — A centered call-to-action block: heading, supporting copy, and one or two CTA links.
- Call To Action Boxed: npx payload-components add call-to-action-boxed — A boxed call-to-action block: heading, copy, and CTA links inside a nested panel.
- Call To Action Signup: npx payload-components add call-to-action-signup — An email-capture call-to-action block: heading, copy, and a form that posts to a same-origin endpoint.
- Team Roster: npx payload-components add team-roster — A team section that groups members into titled departments, each a grid of avatars with name and role.
- Team Grid: npx payload-components add team-grid — A team section with a heading, intro, and a responsive grid of member photo cards that reveal role on hover.
- Faq Accordion: npx payload-components add faq-accordion — A centered FAQ accordion of question/answer items with an optional CTA — the base of the FAQ family.
- Faq Split: npx payload-components add faq-split — A two-column FAQ pairing a sticky heading and CTA with an accordion of question/answer items.
- Faq Card: npx payload-components add faq-card — A centered FAQ accordion wrapped in a card with an optional CTA below.
- Faq Icons: npx payload-components add faq-icons — An FAQ accordion with a per-question icon picked from a fixed allowlist.
- Faq Grouped: npx payload-components add faq-grouped — An FAQ split into titled, icon-tagged category groups of accordions.
- Faq Grid: npx payload-components add faq-grid — A static two-column grid of question/answer cards — every answer visible, no accordion.

## FAQ
### 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.