Stat Pill
Show one live figure in a capsule, with its unit and how it's changing.
import { StatPill } from '@youj/react'
Installation & usage
npm i @youj/reactFor an app already set up with npx @youj/cli init, which installs the peers (@youj/core, @youj/motion, motion and Base UI) and wires the provider. New app? Start at Installation.
Use a stat pill for a figure people glance at while they work: the CPU load in an editor, the latency of a stream, the size of a cache. It shows an icon, the figure's name, the value with its unit, and optionally how it's moving, either a change since the last reading or a small trend line.
import { StatPill } from '@youj/react'
import { ActivityIcon } from '@youj/icons'
<StatPill label="Latency" icon={<ActivityIcon />} value={42} unit="ms" delta={-6} better="down" />format takes Intl.NumberFormat options for the value. Without it, the value keeps its own decimals. trend takes recent readings, oldest first, and draws them as a small line with a dot on the latest one.
Description
Three pills: a live CPU load with a trend line, a latency that fell by 6 ms, and a cache that grew by 0.3 GB.
delta is the change since the last reading. better says which way is good, so the change is tinted to match. The default is up. Use down for latency and errors, and none for figures such as loudness, where a change is just news and stays neutral.
Code
stat-pill-demo.tsx, the Demo story. The component itself comes from the package.
Reference
Propslabel, value, format… (11)
Props
| Prop | Type | |
|---|---|---|
labelRequired | stringWhat the figure is: the eyebrow before it. Keep it short ("CPU", "Tempo"). | – |
valueRequired | number | – |
format | Intl.NumberFormatOptionsIntl.NumberFormat options for the value: compact notation, fraction digits, percent. Default: the value’s own decimals, so a count never passes through fractions. | – |
locale | stringDefault: the YoujProvider locale. | – |
unit | ReactNodeSet small and muted after the value: "ms", "fps", "GB". | – |
icon | ReactNodeA decorative icon in a disc at the start. | – |
delta | numberThe change since the last reading, signed, in the value's terms: 4.2 reads "▲ 4.2". | – |
deltaFormat | Intl.NumberFormatOptionsIntl.NumberFormat options for the delta. Default: up to one decimal. | – |
better | 'up' | 'down' | 'none'Which way is good: default 'up' | 'up' |
trend | readonly number[]Recent readings, oldest first: a word-sized trend with a dot on the latest. | – |
size | 'sm' | 'default'
default `default` | `default` |
StylingParts and data attributes
Styling
Parts: stat-pill, stat-pill-icon, capsule-label, stat-pill-value, capsule-unit and stat-pill-delta (with data-direction and data-tone).
MotionNew value, new reading
Motion
| Moment | Tokens | ||
|---|---|---|---|
| New valuecounts from where it is to the new value; the first reading is shown as it is | duration.deliberateease.emphasized560ms · cubic-bezier(0.6, 0, 0.1, 1) | 560mscubic-bezier(0.6, 0, 0.1, 1) | |
| New readingthe trend line morphs point by point and its dot glides to the latest reading | duration.slow340ms | 340ms |
Reduced motion
Values and the trend change at once.
Accessibilityannouncements
Accessibility
- The name, value and unit are plain text, so they're read in order.
- The direction of a change is spoken ("Up 4.2"), so it isn't carried by color alone.
- The icon and the trend line are decorative.
- If the figure updates often, don't make it a live region; people can read it when they want.