Page blocksStats

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-migrations

Installation

npx payload-components add stats-card
Manualnpx shadcn@latest add https://www.payload-components.xyz/r/stats-card.json

The 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
  1. 01
    Stars on GitHub+1,200
  2. 02
    Conversion rate56%
  3. 03
    Powered apps+500
  1. 1Add the block to a Page from the layout block picker.
  2. 2Fill the fields as above.
  3. 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.

statsFields.tsshared
config.ts
Component.tsx

Edits

Wires StatsCard into the project in 4 places.

  • 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 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.

In this family