FreshnessBadge
A moment written for a human, with the machine-readable value kept beside it.
@luc/ui/dataExamples
Default
<Timestamp value="2026-10-06T14:05:00Z" style="datetime" timeZone="UTC" />Usage
import { FreshnessBadge } from "@luc/ui/data";<Timestamp value="2026-10-06T14:05:00Z" style="datetime" timeZone="UTC" />Package setup — peer requirements, the stylesheet and the provider — is on installation.
API
Read from the published TypeScript API, so a prop that is not listed here does not exist and a default that is listed is the one the compiler sees.
| Export | Kind | Signature |
|---|---|---|
FreshnessBadge | 7 documented props | ({ className, updatedAt, freshSeconds, staleSeconds, now, showAge, locale, ...props }: FreshnessBadgeProps) => import("@types/react").JSX.Element |
Timestamp | 6 documented props | ({ className, value, display, style, locale, timeZone, now, ...props }: TimestampProps) => import("@types/react").JSX.Element |
FreshnessBadge props
Type: FreshnessBadgeProps
Values the compiler reads from the declaration.
| Prop | Type | Default | Notes |
|---|---|---|---|
freshSeconds? | number | undefined | — | |
locale? | string | undefined | — | |
now? | number | Date | undefined | — | |
showAge? | boolean | undefined | — | Render the age next to the level, e.g. "Fresh · 42s". |
size? | "sm" | "md" | undefined | — | |
staleSeconds? | number | undefined | — | |
updatedAt | string | number | Date | null | undefined | — |
Timestamp props
Type: TimestampProps
Values the compiler reads from the declaration.
| Prop | Type | Default | Notes |
|---|---|---|---|
display? | "absolute" | "relative" | undefined | — | `relative` (3m ago) or `absolute` (Sep 25, 14:05 UTC). |
locale? | string | undefined | — | |
now? | number | Date | undefined | — | Fixed "now" for deterministic rendering (tests, screenshots). |
style? | "time" | "date" | "datetime" | undefined | — | |
timeZone? | string | undefined | — | |
value | string | number | Date | null | undefined | — |
Guidelines
Do
- Pass `timeZone` explicitly for a value that is not the reader's local time — a market close, a release window.
- Use `FreshnessBadge` for “updated 4 minutes ago” and `Timestamp` for the exact value; the two answer different questions.
Don't
- Format a date with `toLocaleString()` in the page and pass the result as `value`; the component cannot recover the time zone from it.
Accessibility
The rendered text is the full date and time, and the relative form keeps the absolute value in its `title`, so a reader gets both without hovering.
Family
Data display
Dense, sortable, scannable: the surfaces a real product reads numbers from.
17 documented entries in this family. Open the family index
Related