StatsBand

A band of three or four headline numbers that count up when scrolled into view, each with a tiny visual that proves it (trend, uptime, distribution or world map) and a context line on hover or focus.

When to use

• Landing and about pages that back a claim with a few hard numbers: usage, uptime, speed, reach.
• When each number benefits from a small chart rather than a bare figure.
• Not for live dashboards or KPIs that change while you watch: use MetricCard, Sparkline or the chart components.
• Not for more than four numbers; split them or use a table.

Usage

import { StatsBand } from "@/components/iris/blocks/stats-band/stats-band";

h(StatsBand, {
  layout: "divided",
  title: "Verification at a glance",
  description: "Rentals GR workspace, sessions from 1 to 22 Oct 2026.",
  stats: [
    {
      value: 1284,
      label: "Sessions this month",
      detail: "Rentals GR workspace",
      context: "Up from 1,090 in September",
      visual: { kind: "trend", values: [612, 701, 820, 958, 1090, 1284] },
    },
    {
      value: 99.9,
      decimals: 1,
      suffix: "%",
      label: "Webhook deliveries on the first try",
      visual: { kind: "uptime", days: ninetyDays },
    },
    {
      value: 6,
      suffix: "min",
      label: "Median time to decision",
      visual: { kind: "distribution", bins: [4, 12, 19, 16, 11, 8, 6], max: 14, marker: 6 },
    },
    {
      value: 7,
      label: "Countries verified",
      visual: {
        kind: "map",
        points: [
          [23.7, 38],
          [21, 52.2],
          [12.5, 41.9],
        ],
      },
    },
  ],
});

Props

Prop	Type	Default	Description
stats	Stat[]	4 sample stats from an ErmisAI newsroom desk	{ value, label, prefix?, suffix?, decimals?, notation?: "standard" | "compact", detail?, context?, visual? }. Three or four read best.
layout	"plain" | "divided"	"plain"	plain floats on whitespace; divided sets the stats in a hairline grid ruled above and below.
title / description	string	none	Optional heading and supporting line.
duration	number	1.6	Seconds each number takes to count up.
locale	string	"en-US"	Number formatting locale (fixed so server and client agree).
className	string	none	Extra class.

visual is one of { kind: "trend", values } (sparkline, oldest first), { kind: "uptime", days } (one bar per day as a percentage), { kind: "distribution", bins, max, marker } (histogram with bars below the marker inked) or { kind: "map", points: [lng, lat][] } (dotted world map).

Notes

• Numbers count up once, the first time 40% of the list is in view; the visual draws in after the number lands.
• context replaces detail while the stat is hovered or focused, so keep it to one line.
• The list is a dl; final values are present for screen readers. Reduced motion shows final numbers and visuals immediately.
• Visuals draw in ink-2 and line-strong and take the accent while their stat is hovered or focused; the layout follows the band's own width (container queries at 800 and 520 px), not the viewport.