Installation

npx payload-components add stats-grid

What it installs

Copies 3 source files into your project:

src/blocks/shared/statsFields.tsshared
src/blocks/StatsGrid/config.ts
src/blocks/StatsGrid/Component.tsx

…and makes 4 edits to wire the block into your project:

Registers the block	`src/collections/Pages/index.ts`
Maps the renderer	`src/blocks/RenderBlocks.tsx`
Regenerates types	`src/payload-types.ts`
Regenerates the admin import map	`src/app/(payload)/admin/importMap.js`

Registers the blocksrc/collections/Pages/index.ts

Maps the renderersrc/blocks/RenderBlocks.tsx

Regenerates typessrc/payload-types.ts

Regenerates the admin import mapsrc/app/(payload)/admin/importMap.js

statsFields.ts is the shared field core for this family — every variant composes it. Editing it updates each installed block at once, and re-running an install never overwrites a copy you have changed.

Re-running the install converges: it detects existing wiring, skips it, and records install state in .payload-components/state.json.

Content model

eyebrow and title come from the shared statsFields base that every Stats variant spreads; description and metrics are specific to this variant. Metric values stay strings, so editors can enter percentages, signed values, counts, or abbreviated totals without formatting logic.

Prop

Type

Each item in metrics carries:

Prop

Type

Usage

Add the block to a page. In the Payload admin, open (or create) a Page and add the StatsGrid block to its layout.

Fill the content. Complete the fields from the content model above — the component ships sample content you can start from.

Publish. Save and publish the page; the block renders through RenderBlocks on the frontend, fully typed — no extra wiring.

Requirements

Target: payload-website-starter, payload-blocks-app
Payload: v3
Next.js: 15 / 16
shadcn UI: badge

Your project must already expose components.json, src/payload.config.ts — the surfaces payload-components add patches. The CLI verifies this against the support matrix before touching anything.

Layout adapted from tailark/blocks (MIT), retokenized onto the Payload Components design system.

In this family

stats-proof

Stats ProofA proof section pairing narrative, prominent string metrics, and a semantic customer quote.

stats-gridcurrent

Stats GridHeading and intro above a responsive grid of large string metrics on rule-topped columns.

stats-card

Stats CardA centred heading above one divided panel that splits metrics into equal columns.

stats-inline

Stats InlineHeading and intro above rule-topped rows where each figure reads as one sentence.