DataFreshness
StableSays how fresh the numbers are, in words and an icon.
Also known as last updated, live indicator, stale data
Install with npm install @tattva/ui (setup), or copy the code from the kit in Downloads.
Each status
<div className="flex flex-wrap gap-2"><DataFreshness status="live" /> <DataFreshness status="delayed" delayMinutes={15} /> <DataFreshness status="stale" asOf="2026-10-07T09:57:00Z" now="2026-10-07T10:00:00Z" /> <DataFreshness status="simulated" /> <DataFreshness status="closed" /></div>Live has a pulsing dot. The others have an icon and their own words.
When to use it
Tells people whether to trust a number as it is, or check its age first.
Made of: Dot or icon · Label · Hidden live message (stale only)
Use it for
- Beside a price or a chart that updates.
- Marking demo or simulated data.
- Showing that a market is closed.
Not for
- A general status tag: use Badge.
- A line of case or order state: use StatusLine.
- A level or progress value: use Meter.
Do and avoid
Do
- Show it whenever numbers can be old, delayed or made up.
- Pass delayMinutes with the real delay.
- Use simulated for demo data.
Avoid
- Do not mark stale data in a warning or danger tone.
- Do not use it as a general badge.
- Do not pass a status of live when the feed is down.
On a phone
- It stays on one line and fits its text, so it works in a header or a card on a narrow screen.
- It shows the status in words and an icon, so nothing depends on hover.
Properties
| Prop | Type | Default | Description |
|---|---|---|---|
| status | "live" | "delayed" | "stale" | "simulated" | "closed" | none | The status to show. If left out, it is worked out from asOf and now: live until staleAfter seconds, then stale. |
| asOf | string | none | When the data was last updated, in ISO time. |
| now | string | none | The current time in ISO, for docs and tests. By default the real time, refreshed every second while the status is worked out. |
| delayMinutes | number | 15 | Minutes shown in the delayed label. |
| staleAfter | number | 60 | Seconds after which computed data counts as stale. |
| className | string | none | Classes for the span. |
"Show code under the preview gives the code for the example on the stage."
In Figma
In Figma, one DataFreshness switches all of this from its properties panel, across 5 variants. Each property sets the React prop beside it, so design and code use the same names.
| Figma property | React | Values |
|---|---|---|
| Status | status | Live, Delayed, Stale, Simulated, Closed |
States
States this part has beyond its default look. Build each one your screen can reach. States set by a property are in the Code tab.
- live
- A pulsing dot shows with the word Live. The dot is still with reduced motion.
- becomes stale
- When a worked-out status turns stale, a hidden polite message is read once.
- no time
- With no status and no valid asOf, it reads Stale.
Tokens
Change one of these and every part that uses it follows.
--sunken--line--fg-muted--unsure-soft--unsure-fg--up--radius-control
Built in
- It is a plain span with words, so it is not a live region.
- Every status has words and a dot or icon. Colour is never the only cue.
- A hidden polite message is read once, only when the status changes to stale.
- The pulsing dot only pulses when motion is allowed. Otherwise it is still.
What you need to do
- Place it next to the numbers it describes.
- Pass asOf in ISO time when you want it worked out for you.
Built toward WCAG 2.2 AA and checked automatically; no independent audit yet. Read the accessibility guide