Stats Grid
Heading and intro above a responsive grid of large string metrics on rule-topped columns.
v0.2.0Page blockpayload-website-starter
import type { Block } from 'payload'
import { statsFields, statsMetricFields } from '@/blocks/shared/statsFields'
export const StatsGrid: Block = {
slug: 'statsGrid',
// Existing apps must migrate stored data before adopting this identifier:
// https://www.payload-components.xyz/docs/registry#installed-source-and-migrationsimport type { Block } from 'payload'import { statsFields, statsMetricFields } from '@/blocks/shared/statsFields'export const StatsGrid: Block = { slug: 'statsGrid', // Existing apps must migrate stored data before adopting this identifier: // https://www.payload-components.xyz/docs/registry#installed-source-and-migrations dbName: 'pc_sta_gri', interfaceName: 'StatsGridBlock', admin: { group: 'Stats', }, fields: [ // Shared stats core (eyebrow, title). Variant-specific fields follow; edit the // shared shape in @/blocks/shared/statsFields. ...statsFields, { name: 'description', type: 'textarea', custom: { payloadComponents: { localization: 'localized' } }, }, { name: 'metrics', type: 'array', required: true, minRows: 2, maxRows: 8, admin: { initCollapsed: true, }, // Shared metric shape — see @/blocks/shared/statsFields. fields: statsMetricFields, }, ], labels: { plural: 'Stats Grid Blocks', singular: 'Stats Grid', },}import React from 'react'import type { StatsGridBlock as StatsGridBlockData } from '@/payload-types'import { Badge } from '@/components/ui/badge'import { cn } from '@/utilities/ui'// Layout adapted from tailark/blocks (MIT) — re-implemented as a Payload block.type Props = StatsGridBlockData & { id?: string className?: string disableInnerContainer?: boolean}export const StatsGridBlock: React.FC<Props> = ({ className, description, disableInnerContainer, eyebrow, id, metrics, title,}) => { return ( <section className={cn('container', className)} id={id ? `block-${id}` : undefined}> <div className="overflow-hidden rounded-frame border border-border/70 bg-card/35 px-6 py-10 sm:px-8 lg:px-12 lg:py-14"> <div className={cn('flex flex-col gap-12', { 'mx-auto max-w-5xl': !disableInnerContainer, })} > <div className="flex flex-col gap-4"> {eyebrow ? ( <Badge variant="outline" className="w-fit rounded-full px-3 py-1 uppercase tracking-eyebrow"> {eyebrow} </Badge> ) : null} <h2 className="text-4xl font-medium tracking-display text-balance sm:text-5xl">{title}</h2> {description ? ( <p className="max-w-2xl text-lg leading-7 text-muted-foreground">{description}</p> ) : null} </div> {metrics && metrics.length > 0 ? ( <dl className="grid grid-cols-2 gap-x-6 gap-y-10 md:grid-cols-4"> {metrics.map((metric, index) => ( <div key={metric.id ?? `${metric.value}-${index}`} className="flex flex-col-reverse border-t border-border/70 pt-5" > <dt className="mt-2 text-sm leading-6 text-muted-foreground">{metric.label}</dt> <dd className="text-4xl font-medium tracking-display text-foreground"> {metric.value} </dd> </div> ))} </dl> ) : null} </div> </div> </section> )}import type { Field } from 'payload'/** * Shared field core for the Stats component family. * * Every stats variant (stats-proof, stats-grid, stats-card, stats-inline, …) * spreads `statsFields` first for the shared eyebrow/title heading, then appends * its own variant-specific shape — the narrative-plus-quote proof panel, the bare * number band, the divided card row, or the bordered sentence rows. Editing the * shared heading here updates every installed stats block at once, so the family * never drifts field-by-field across a repo. * * `statsMetricFields` is the one-figure shape (display value plus its label) * reused by every variant, so a metric reads the same wherever it appears. The * value stays a free-text string rather than a number: real stat bands mix * `99.9%`, `+1,200`, `22M`, and `24/7`, and formatting them belongs to the editor * rather than to a locale-sensitive number formatter at render time. * * Installed once per repo at `src/blocks/shared/statsFields.ts`; re-running * `payload-components add stats-*` never overwrites a copy you have already edited. */export const statsFields: Field[] = [ { name: 'eyebrow', type: 'text', custom: { payloadComponents: { localization: 'localized' } }, }, { name: 'title', type: 'text', custom: { payloadComponents: { localization: 'localized' } }, required: true, },]export const statsMetricFields: Field[] = [ { name: 'value', type: 'text', custom: { payloadComponents: { localization: 'global' } }, required: true, }, { name: 'label', type: 'text', custom: { payloadComponents: { localization: 'localized' } }, required: true, },]Installation
npx payload-components add stats-gridnpx shadcn@latest add https://www.payload-components.xyz/r/stats-grid.jsonThe registry copy brings the source files only; register the block and map its renderer yourself, or let the CLI command above do both.
Usage
Editors add Stats Grid from a Page layout's block picker. This is the form they fill.
Stats Grid
Block- Eyebrow
- By the numbers
- Title
- Growth teams can measure.
- Description
Every workspace reports the same governed metrics, so the numbers on this page are the numbers in the product.
- Metrics
- 01Integrations90+
- 02Productivity boost56%
- 03Customer support24/7
- 04Active users10k+
- 01
- 1Add the block to a Page from the layout block picker.
- 2Fill the fields as above.
- 3Publish. RenderBlocks renders the block, fully typed.
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
What it installs
Composition
How the block hangs together in Payload
Pageslayout[]StatsGrideyebrowtitledescriptionmetrics[]valuelabel
- Fields
src/blocks/StatsGrid/config.ts- Render
src/blocks/StatsGrid/Component.tsx
Files
Copies 3 files into your project. Files tagged shared are reused across the family.
Edits
Wires StatsGrid into the project in 4 places.
| 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 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
statsFields.ts is shared source for this component family. Components that install the same path reuse your local copy, and re-running an install never overwrites a copy you have changed.Re-running the install detects existing source and wiring, then records install state in .payload-components/state.json.
Requirements
- Target
- payload-website-starter, payload-blocks-app
- Payload
- v3 (3.25 or newer) / v4 (experimental)
- Next.js
- 15 / 16 with v316 (16.4 or newer) with v4
- shadcn UI
badge
Payload v4 support is experimental: it needs Next.js 16 (16.4 or newer) and Node.js 24.22.1 or newer. Payload v3 (3.25 or newer) stays fully supported.
Your project must already expose components.json, src/payload.config.ts, the surfaces patched by payload-components add. The CLI verifies this against the support matrix before touching anything.
Layout adapted from tailark/blocks (MIT), retokenized onto the Payload Components design system.