Freshness stamp

Pro

How old a piece of knowledge is (Candor's FreshnessStamp). "Read 3 hours ago" when known; "Never read" when not; overdue when older than its schedule allows. A timestamp in the future is clamped and called out rather than shown as "in 2 hours".

Markdown

Preview

Install

With the Candor CLI

First time? Get started sets up the registry and theme. Or with shadcn directly: npx shadcn@latest add @candor/freshness-stamp

Brings in: locale, relative-time, utils · npm: lucide-react@^1.67.0

Usage

TSX · The example above

"use client"

import { FreshnessStamp } from "@/components/freshness-stamp"

const hoursAgo = (h: number) => new Date(Date.now() - h * 3_600_000).toISOString()

export default function Example() {
  return (
    <div className="flex flex-col gap-2">
      <FreshnessStamp readAt={hoursAgo(2)} everyHours={24} />
      <FreshnessStamp readAt={hoursAgo(52)} everyHours={24} verb="Synced" />
      <FreshnessStamp readAt={null} />
    </div>
  )
}

<FreshnessStamp>

Prop	Type	Default	Description
readAtrequired	`string \| null`	—	When it was last read (ISO date). null means it never was, shown as "Never read".
everyHours	`number \| undefined`	—	Expected re-read interval; overdue past 1.5× this.
verb	`string \| undefined`	—	The word before the time, e.g. "Synced" or "Checked".
className	`string \| undefined`	—	Extra classes for the outer element.

Strings

The fixed words, in English by default. Change any of them under freshnessStamp in <LocaleProvider strings={{ … }}>; the table is exported as freshnessStampStrings.

Key	English
read	Read
never	Never {verb}
onDate	on {date}
stamp	{verb} {when}
stampOverdue	{verb} {when} · overdue
timeUnknown	{verb} time unknown
future	This timestamp is ahead of the clock; treat it as unknown.