Stats Card
A centred heading above one divided panel that splits metrics into equal columns.
v0.2.0Page blockpayload-website-starter
import type { Block } from 'payload'
import { statsFields, statsMetricFields } from '@/blocks/shared/statsFields'
export const StatsCard: Block = {
slug: 'statsCard',
// 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 StatsCard: Block = { slug: 'statsCard', // Existing apps must migrate stored data before adopting this identifier: // https://www.payload-components.xyz/docs/registry#installed-source-and-migrations dbName: 'pc_sta_car', interfaceName: 'StatsCardBlock', admin: { group: 'Stats', }, fields: [ // Shared stats core (eyebrow, title). Variant-specific fields follow; edit the // shared shape in @/blocks/shared/statsFields. ...statsFields, { name: 'metrics', type: 'array', required: true, minRows: 2, maxRows: 4, admin: { description: 'Each metric becomes one column of the divided panel — two to four keeps the row readable.', initCollapsed: true, }, // Shared metric shape — see @/blocks/shared/statsFields. fields: statsMetricFields, }, ], labels: { plural: 'Stats Card Blocks', singular: 'Stats Card', },}import React from 'react'import type { StatsCardBlock as StatsCardBlockData } 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 = StatsCardBlockData & { id?: string className?: string disableInnerContainer?: boolean}export const StatsCardBlock: React.FC<Props> = ({ className, 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-10', { 'mx-auto max-w-4xl': !disableInnerContainer, })} > <div className="flex flex-col items-center gap-4 text-center"> {eyebrow ? ( <Badge variant="outline" className="w-fit rounded-full px-3 py-1 uppercase tracking-eyebrow"> {eyebrow} </Badge> ) : null} <h2 className="text-3xl font-medium tracking-title text-balance sm:text-4xl">{title}</h2> </div> {metrics && metrics.length > 0 ? ( <dl className="grid divide-y divide-border/70 rounded-panel border border-border/70 bg-background/85 md:auto-cols-fr md:grid-flow-col md:divide-x md:divide-y-0"> {metrics.map((metric, index) => ( <div key={metric.id ?? `${metric.value}-${index}`} className="flex flex-col-reverse gap-2 px-6 py-8 text-center" > <dt className="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-cardnpx shadcn@latest add https://www.payload-components.xyz/r/stats-card.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 Card from a Page layout's block picker. This is the form they fill.
Stats Card
Block- Eyebrow
- Adoption
- Title
- Trusted where the numbers matter.
- Metrics
- 01Stars on GitHub+1,200
- 02Conversion rate56%
- 03Powered apps+500
- 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;
metrics is specific to this variant. The panel distributes its columns evenly from the row count,
so two, three, or four metrics all stay balanced without a layout setting.
Prop
Type
Each item in metrics carries:
Prop
Type
What it installs
Composition
How the block hangs together in Payload
Pageslayout[]StatsCardeyebrowtitlemetrics[]valuelabel
- Fields
src/blocks/StatsCard/config.ts- Render
src/blocks/StatsCard/Component.tsx
Files
Copies 3 files into your project. Files tagged shared are reused across the family.
Edits
Wires StatsCard 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.