Statistic

Displays a single named figure. Given a previous value, it works out the change and shows it alongside.

import { Statistic } from 'neba';

<Statistic label="Monthly recurring revenue" value={48210} prefix="$" previousValue={42800} />;

Props

Prop	Type	Default	Description
label	ReactNode	—	The name of the number. Card calls the same slot `title`, but what this names is a *value*: which is the thing the library already spells `label` on every field it has
value *	ReactNode	—	The figure. A number is formatted; anything else is rendered exactly as given: a string for the values that are not numbers, or a node such as an AnimateCounter
format	Intl.NumberFormatOptions	—	How to write a numeric value: the same prop the progress indicators take. Without it a number is grouped by the reader’s own locale and otherwise left alone
locale	string	the reader's	Which language the figure is written in: the same prop every chart takes. A Statistic sits next to the charts in a dashboard, so a locale set on one of them has to be settable on all
prefix	ReactNode	—	Set before the figure: a currency sign
unit	ReactNode	—	Set after the figure: %, MB, 명. A second slot rather than one adornment with a side, because a currency symbol leads its number and a unit follows it
icon	ReactNode	—	A glyph before the label
previousValue	number	—	The figure this one is compared against: last month’s, the target. Passing it is what makes the delta appear
delta	'percent' | 'absolute' | 'both' | 'none'	'percent'	How the difference is written. Percentage by default, because a report is nearly always asking how much a figure has moved rather than by how many. With a previousValue of 0 there is nothing to divide by, so it falls back to the difference itself
betterWhen	'up' | 'down'	'up'	Which direction counts as good, and so which way the delta is coloured. `up` for revenue, `down` for churn and error rate and page weight. Not decoration: green-for-larger on a bounce rate says the opposite of what the report means, and says it to exactly the reader who is skimming
caption	ReactNode	—	A line under the figure: "vs. last month"
alignshared	'start' | 'center' | 'end'	'start'	Where the block sits in the card. `center` for a row of tiles that read as one band
variantshared	'solid' | 'outline' | 'text'	'outline'	Weight of the surface: Box’s own, because a Statistic is a Box with an arrangement on it
sizeshared	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	The figure’s type scale, and the sheet’s padding and radius
colorshared	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'primary'	Semantic colour role. Arbitrary colour values are not accepted
densityshared	'default' | 'compact'	'default'	Padding only: never the height, never the type scale
elevationshared	0 | 1 | 2 | 3	0	Drop shadow depth. 0 means no shadow at all
children	ReactNode	—	Anything below the caption: a sparkline, a ProgressLinear against a target
transitionshared	NebaTransition	—	An entrance animation, run once on mount (transition="zoom"). Wrap it in an Animate* component for a trigger or a replay

Every native <div> attribute passes through, along with every Box prop. The delta renders as a Chip.

Examples

previousValue · delta · betterWhen

Pass previousValue and the change against the current value is calculated and shown. delta decides whether that change is written as a proportion, as the difference, or as both.

betterWhen says which direction is good news. Revenue is better up, churn is better down: without it there is no way to colour the delta.

import { Grid, GridContainer, Statistic } from 'neba';

/**
 * `betterWhen` is the whole reason the delta can be trusted. Both cards below
 * went *up*; only one of them is good news, and the colour has to say which.
 */
export default function StatisticComparison() {
  return (
    <GridContainer spacing={3} padded={false}>
      <Grid span={{ xs: 12, sm: 6 }}>
        <Statistic
          label="Signups"
          value={3120}
          previousValue={2740}
          caption="betterWhen up (the default)"
          className="h-full"
        />
      </Grid>
      <Grid span={{ xs: 12, sm: 6 }}>
        <Statistic
          label="p95 latency"
          value={412}
          unit="ms"
          previousValue={366}
          betterWhen="down"
          caption="betterWhen down"
          className="h-full"
        />
      </Grid>

      <Grid span={{ xs: 12, sm: 6 }}>
        <Statistic
          label="Open incidents"
          value={7}
          previousValue={12}
          betterWhen="down"
          delta="absolute"
          caption='delta="absolute"'
          className="h-full"
        />
      </Grid>
      <Grid span={{ xs: 12, sm: 6 }}>
        <Statistic
          label="Seats used"
          value={188}
          previousValue={160}
          delta="both"
          caption='delta="both"'
          className="h-full"
        />
      </Grid>
    </GridContainer>
  );
}

The figure and the delta change shape as well as colour: a rising arrow, a falling one, a short dash when nothing moved. Direction is never carried by colour alone.

icon · unit · caption · align

icon sits before the label and unit after the figure. children is the slot under the figure, for a ProgressLinear against a target or a Sparkline. align="center" is for a row of tiles laid out as one band.

prefix and unit are separate props because they are typographically different: a currency symbol leads its number, a unit follows it.

import { Grid, GridContainer, Icon, ProgressLinear, Statistic } from 'neba';

function UsersIcon() {
  return (
    <svg viewBox="0 0 16 16" fill="none">
      <circle cx="6" cy="5.5" r="2.5" stroke="currentColor" strokeWidth="1.5" />
      <path
        d="M1.75 13c0-2.3 1.9-3.75 4.25-3.75S10.25 10.7 10.25 13"
        stroke="currentColor"
        strokeWidth="1.5"
        strokeLinecap="round"
      />
      <path
        d="M11 4.5a2 2 0 0 1 0 4M12 9.75c1.4.45 2.25 1.6 2.25 3.25"
        stroke="currentColor"
        strokeWidth="1.5"
        strokeLinecap="round"
      />
    </svg>
  );
}

/**
 * The slots, and what a Statistic looks like when it is asked to carry more than
 * a number: an icon on the label, a unit on the figure, and something of your
 * own underneath.
 */
export default function StatisticAnatomy() {
  return (
    <GridContainer spacing={3} padded={false}>
      <Grid span={{ xs: 12, sm: 6 }}>
        <Statistic
          icon={<Icon icon={<UsersIcon />} size="sm" />}
          label="Seats"
          value={188}
          unit="/ 250"
          caption="75% of the plan"
          className="h-full"
        >
          <ProgressLinear value={75} label="Seats used" />
        </Statistic>
      </Grid>

      <Grid span={{ xs: 12, sm: 3 }}>
        <Statistic
          label="Uptime"
          value="99.98%"
          align="center"
          variant="solid"
          color="success"
          className="h-full"
        />
      </Grid>

      <Grid span={{ xs: 12, sm: 3 }}>
        <Statistic
          label="Median build"
          value="3m 12s"
          align="center"
          variant="text"
          size="sm"
          className="h-full"
        />
      </Grid>
    </GridContainer>
  );
}

format

format is passed straight through as Intl.NumberFormat options. Without it a number is only digit-grouped for the reader's locale. A string value is printed unformatted, so figures that are not numbers still work.

<Statistic label="Revenue" value={48210} format={{ style: 'currency', currency: 'USD' }} />
<Statistic label="Conversion" value={0.0423} format={{ style: 'percent', maximumFractionDigits: 1 }} />
<Statistic label="Median build" value="3m 12s" />

A previousValue of 0 makes the proportion undefined, so the absolute difference is shown regardless of the delta setting.

locale

locale decides which language the figure and its delta are written in. It is the same prop every chart takes, so one dashboard can set the same value on a Statistic and on the LineChart beside it. Without it the reader's own locale is used.

<Statistic label="Revenue" value={1234.5} locale="de-DE" format={{ minimumFractionDigits: 1 }} />