Components Primitives
Stat
Give a meaningful number the context it deserves. Pair a value with a unit, label, and optional caption.
On this page
Examples
Lead with one key result. The default size leaves room for a short explanatory caption.
37%
Adoption
Illustrative increase in product adoption within 90 days.
Preview only: surrounding canvas and spacing. All metrics are illustrative.
'use client';
import { StatBlock } from '@coreux/ui';
export default function Large() {
return (
<StatBlock
value="37"
unit="%"
label="Adoption"
caption="Illustrative increase in product adoption within 90 days."
/>
);
}
Usage
Use StatBlock for a proof point in a marketing page, a result in a case study, or a compact group of supporting metrics. It displays the text you give it; it does not calculate, format, or animate a number.
Make the number meaningful
Keep the label short. Use the caption to explain the time period, comparison, or source. Put currency symbols in the value and suffixes such as “%” in the unit.
Give each metric a role
Use Large for the lead result and Small for supporting figures. Choose OnDark when your composition has a dark surface; the ivory tone only changes text colors.
The examples use illustrative data, not measured CoreUX outcomes. Replace values and context with verified information before publishing.
Props
value and label are required strings. The defaults render a large statistic in ink. There is no numeric parsing, length validation, or automatic unit formatting.
| Prop / type | Default | Description |
|---|---|---|
valueRequiredstring | Required | Display-ready text. Format signs, currency, separators, and precision before passing it. |
unitstring | undefined | A smaller suffix beside the value, such as %, x, or M. Omitted when undefined. |
labelRequiredstring | Required | A concise name for the metric, rendered visually in uppercase. |
captionstring | undefined | Optional context beneath the label. Omitted when undefined; an empty string still renders a paragraph. |
tone"ink" | "ivory" | "ink" | ink uses navy values and slate labels; ivory uses ivory values and pale steel labels. Does not set a background. |
size"sm" | "lg" | "lg" | lg: 36 px value and 20 px unit. sm: 18 px value and 14 px unit. Labels stay 12 px; captions stay 14 px (at a 16 px root). |
classNamestring | undefined | Classes merged onto the outer div with the package cn utility. Does not forward arbitrary HTML or ARIA attributes. |
Accessibility & layout
Readable text, with context supplied by you
StatBlock renders a div containing paragraphs for the value, label, and optional caption. The unit is a span inside the value paragraph. It is not a heading, live region, or interactive control. All content remains real DOM text in that reading order.
Use a surrounding section and heading to identify a group of statistics. Spell out ambiguous units in nearby text. The component does not forward HTML attributes such as aria-label; put any needed semantics on your wrapper. Check contrast when choosing the surrounding background, particularly with the ivory tone.
The container controls the layout
There are no viewport breakpoints or automatic size changes. The value uses 36 px at the default lg size and 18 px at sm, assuming a 16 px root. Labels and captions can wrap at spaces; long unbroken values may overflow. Select a size and test your actual text at narrow widths and browser zoom.
The Small example adds flex wrapping to the original three-stat seed so the row can fit a narrow container. That behavior belongs to its copied wrapper, not to StatBlock. The OnDark example includes its required navy background; changing tone alone does not create a dark surface.
Consumer setup
Browsing, previews, and copying are public. Installing the private @coreux/ui package requires repository read access and permission to use the bundled CoreUX brand fonts.
Follow the one-time installation guide for the pinned Git dependency, Tailwind v4 stylesheet setup, fonts, and troubleshooting. Keep the 'use client' directive in each example; no provider is required.
The quick start walks through a copied StatBlock in a minimal app.
Source & revision
This reference targets @coreux/ui version 0.1.0 at 06f42fd. Types come from its installed declarations; explanations and defaults are checked against this implementation.
Revision and upgrade notes · Contribution and coverage guide
View StatBlock source (repository access required)