Skip to Content

StatsSection

Present numeric metrics, trends, descriptions, and progress with responsive layouts and reduced-motion support.

StatsSection presents consumer-provided values without requiring an external data source. Values may be numbers or formatted strings, with optional prefixes, suffixes, descriptions, trend labels, progress, and emphasis.

Beta API maturity: Beta.

Installation

import { StatsSection, type StatItem } from "@puzzle-ui/pieces";

Variant previews

The animated variant counts numeric values after mount. It renders the final value immediately when prefers-reduced-motion is enabled. String values remain unchanged.

grid - A general-purpose collection of key metrics.

390 × 844

inline - Compact metrics displayed in one flowing row.

390 × 844

cards - Metrics separated into individual cards.

390 × 844

split - A small set of metrics with balanced emphasis.

390 × 844

centered - Metrics centered below a short introduction.

390 × 844

featured - A primary metric supported by secondary values.

390 × 844

horizontal - A flexible horizontal row of statistics.

390 × 844

vertical - Metrics stacked for narrow panels or sidebars.

390 × 844

dashboard - Compact operational values for a dashboard summary.

390 × 844

comparison - Metrics arranged for before-and-after comparisons.

390 × 844

progress - Values that include progress indicators.

390 × 844

animated - Numeric values counted up when motion is allowed.

390 × 844

API

PropTypeDescription
variantStatsVariantSelects one of twelve metric layouts; defaults to grid.
itemsreadonly StatItem[]Data with stable id, label, and required value.
StatItem.prefix / suffixReactNodeOptional content displayed beside the value.
StatItem.trend{ direction: "up" | "down" | "neutral"; label: ReactNode }Direction and consumer-supplied trend description.
StatItem.progressnumberOptional progress percentage, clamped to 0-100.
StatItem.featuredbooleanEmphasizes a metric in supported layouts.
Shared section propsSectionRootProps and heading propsSemantic root, theme, native attributes, heading, actions, and children.

Usage

<StatsSection
  variant="progress"
  title="Quarterly results"
  items={[
    { id: "uptime", label: "Uptime", value: 99.9, suffix: "%" },
    { id: "users", label: "Active users", value: 2400, progress: 75 },
  ]}
/>

Progress values outside 0-100 are clamped for display. Animated values do not use a live region, avoiding continuous announcements to assistive technology.

Accessibility

Use clear labels and meaningful trend descriptions. Progress indicators receive an accessible name based on the string label or item ID. Reduced-motion preferences disable the counter animation.