Stat

Display a single metric with a label, value, supporting context, and an optional trend arrow.

stable
since v0.1.0
1.5 kB
data-display
metric
kpi

Preview

tsx

import { Stat, StatHelp, StatLabel, StatValue } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <Stat>
      <StatLabel>Monthly revenue</StatLabel>
      <StatValue>$48,290</StatValue>
      <StatHelp>Up from $42,960 last month</StatHelp>
    </Stat>
  );
}

With trend arrow

Use StatArrow to surface direction. direction="increase" (default) renders an upward chevron; direction="decrease" flips it. The arrow exposes an aria-label so screen readers announce the trend.

Preview

Open

tsx

import { Stat, StatArrow, StatHelp, StatLabel, StatValue } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <div style={{ display: 'flex', gap: '2rem' }}>
      <Stat>
        <StatLabel>New signups</StatLabel>
        <StatValue>1,482</StatValue>
        <StatHelp>
          <StatArrow direction="increase" /> 23.4% vs last week
        </StatHelp>
      </Stat>
      <Stat>
        <StatLabel>Bounce rate</StatLabel>
        <StatValue>38.2%</StatValue>
        <StatHelp>
          <StatArrow direction="decrease" /> 4.1% vs last week
        </StatHelp>
      </Stat>
    </div>
  );
}

With help text

StatHelp is the slot for comparison context — period-over-period deltas, percentages, or a short explanation.

Preview

Open

tsx

import { Stat, StatHelp, StatLabel, StatValue } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <Stat>
      <StatLabel>Time to first byte</StatLabel>
      <StatValue>184 ms</StatValue>
      <StatHelp>p75 across all regions, last 24 hours</StatHelp>
    </Stat>
  );
}

Stat grid

Group multiple Stats in a CSS grid for KPI dashboards.

Preview

Open

tsx

import { Stat, StatArrow, StatHelp, StatLabel, StatValue } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <div
      style={{
        display: 'grid',
        gridTemplateColumns: 'repeat(3, minmax(0, 1fr))',
        gap: '1rem',
      }}
    >
      <Stat>
        <StatLabel>Revenue</StatLabel>
        <StatValue>$48,290</StatValue>
        <StatHelp>
          <StatArrow direction="increase" /> 12.4%
        </StatHelp>
      </Stat>
      <Stat>
        <StatLabel>Active users</StatLabel>
        <StatValue>9,820</StatValue>
        <StatHelp>
          <StatArrow direction="increase" /> 3.1%
        </StatHelp>
      </Stat>
      <Stat>
        <StatLabel>Churn</StatLabel>
        <StatValue>2.1%</StatValue>
        <StatHelp>
          <StatArrow direction="decrease" /> 0.4%
        </StatHelp>
      </Stat>
    </div>
  );
}

API

PropTypeDefaultDescription

Accessibility

Label, value, and help text share a semantic relationship via DOM proximity — screen readers announce them together.
StatArrow carries an aria-label ("Increased by" / "Decreased by") so the trend direction is announced even when colour alone is ignored.
Color is never the sole cue for direction — pair the arrow with a number or word.
The default icons are decorative (rendered by Lucide); pass children to override with your own glyph.
Use a heading or aria-label on the surrounding card / region when the metric needs more context.

Recipes

Group multiple Stats in a Grid for KPI dashboards.
Use StatHelp for percentage changes or comparison context (“vs last week”, “year to date”).
Combine with LinearProgress for goal-tracking widgets — Stat reports the number, LinearProgress shows progress toward the goal.
Wrap a Stat inside a Card with variant="elevated" for a featured metric on a dashboard.