GrStatistic

• one metric is the main one — revenue, the number of orders, conversion: a large figure is read first;
• a trend is needed beside it — trend with an arrow and the label “+12 % against last week”;
• the number is long — digit grouping and precision by locale, with no manual formatting;
• the value changes before your eyes — animate brings the figure to the new value rather than replacing it;
• the tile is clickable — href/clickable lead into a section with the details.

The component is presentational: it does not load the data and does not compute the delta — it only formats and presents. The trend arrives ready, because “compared to what” is known by the application rather than by the tile.

<GrStatistic title="Revenue" :value="1234567.5" :precision="2" prefix="₽" />

The separators come from the locale through Intl.NumberFormat, and the locale from the i18n adapter of the package. Nothing has to be configured: ru will give 1 234 567,50, and de-DE 1.234.567,50.

The resolution order: groupSeparator/decimalSeparator → the locale prop → the locale of the adapter → the built-in default (a narrow space and a dot). An explicit separator replaces only its own part; the rest of the rules of the locale — grouping by three or by the Indian scheme, the minus sign — the component keeps.

A non-numeric value is printed as it is: “2 h 15 min” and ”—” need no workaround props. The formatting lives in a pure formatStatisticValue function of its own and is available from the package.

A mandatory value that did not arrive is drawn as a dash — the same sign of emptiness with which GrDelta shows a missing quantity — and is explained with a warning in dev mode. A tile with the word undefined looks like data rather than like an error, so that variant is excluded.

<GrStatistic :value="482" trend="up" trend-text="+12.5 % against last week" />

trend sets the colour and the icon of the line, and trendText the text itself. The direction icons are built in; the icon prop to the left of the block accepts a Vue component or an icon class from your build (see “Icons”). The direction is additionally announced with a hidden label (“Growth”, “Decline”, “No change”): the icon is decorative, and “+12.5 %” without context does not tell growth from decline — the colour is not visible to a screen reader either. The label stays with a #trend slot of your own as well.

<GrStatistic title="Average order" :value="14.99" :precision="2" prefix="$" suffix="per order" />

The tile does not draw the record of the quantity — the prefix, the number, the suffix — itself: that is done by the GrValue primitive, shared with GrDelta. The defaults come from there as well: on the left the affix is set like a number ($14.99), on the right it is dimmed and smaller (42 %).

The tile decides only the tone and the type size, and puts them on the container of the quantity — the affixes inherit both. That is why a negative sum turns red as a whole, together with the currency sign, rather than the number apart from it.

What an affix is — a currency, a unit of measurement or a note — is decided by nobody: the styling of both is configured with the --gr-value-* tokens. That is also how a currency on the right (1 284 500 ₽) is obtained, for which the default of the suffix does not fit — the recipe is on the page of the primitive.

<GrStatistic title="Margin" :value="-1240" prefix="₽" polarity="positive-good" />

polarity colours the value by the sign of the quantity itself: positive-good for revenue, negative-good for cost and churn, none when the sign says nothing about quality. Zero is neutral with any polarity, and a non-numeric value (“2 h 15 min”, ”—”) has no sign and gets no tone.

trend colours the line under the value and arrives ready. Neither requires the other: a metric may turn red without a label about the trend, and a label may stand under a neutral value.

An explicit tone is stronger than polarity: an inferred tone is a default rather than a dictate. The same choice of tone is available as a separate deltaTone function — see GrDelta, where it lives.

<GrStatistic title="Revenue" :value="revenue" animate :animate-duration="900" />

animate runs through the numbers when the tile appears (from zero) and on every change of the value — from the previous number rather than from zero: a run from zero on every update of a dashboard would read as a reset of the data.

The duration is set by animateDuration in milliseconds (600 by default). It is deliberately not set with a token: the --gr-duration-* scale ends at 300 ms and describes a change of state — a colour, a border, the appearance of a layer. A run through numbers is a different genre, and its number lives where the tween does — in JS.

Only numbers are run through: “2 h 15 min” and ”—” are set at once. The width of the line does not jerk — the value is set in tabular-nums.

The component reads prefers-reduced-motion itself. The global clamp in base.css holds CSS animations and transitions but not a JS tween — see ../motion.md. Under reduce the value is set instantly, with not a single intermediate frame.

A screen reader hears the final value. While the run is going on, the visible number is marked aria-hidden, and a visually hidden node with the result lives beside it: “1,284,500” on the screen and “743,210” in the ears is not noise but wrong data.

<GrStatistic title="Orders" :value="1284" href="/orders" />

<GrStatistic title="Orders" :value="1284" clickable @click="drill" />

<GrStatistic title="Orders" :value="1284" :as="RouterLink" :to="{ name: 'orders' }" />

The same device as in GrCard and GrListItem: href gives a link, clickable a button, as a tag or a router component of your own (stronger than href). An interactive tile gets a cursor, a highlight and a focus ring; it has no fill of its own — a metric usually lies in a card already, and a second surface would argue with it.

There is no separate ariaLabel: the accessible name is assembled from the content, and the label of the metric is its name.

loading replaces the value with a skeleton of the same height, so that the block does not jump; the area is marked role="status" and contains a hidden loading text.

The #icon, #title, #prefix, #suffix and #trend slots and the default slot (instead of the formatted value) replace the corresponding parts with markup.

The label and the value are output as <dl> → <dt> → <dd>: that is a “term — value” pair rather than two neighbouring blocks a screen reader simply reads in a row. The <dl> appears only together with the label — a definition list without a <dt> would be the same incoherence, only with a claim to semantics.

The trend line stays outside the <dl>: only dt/dd groups are allowed inside a definition list. Its place in the DOM is unchanged, and the layout does not change. The margins of the <dl> and the <dd> are zeroed with a class — the preflight of the package resets them for body alone.

All of the data attributes (data-gr-statistic-title, data-gr-statistic-value, …) are kept: the consumer’s styles written against them keep working.