KQ-775 · FRESHNESS/TAG

Freshness Tag

How old each source is, worn as a tag. Ages are measured from a now the host passes, never a clock; a source past the stale line turns amber on a colour tween and a re-fetch control slides open on snap. Pressing it fires onRefetch, the arrows turn on a linear loop while the host lists the id as fetching, and when a new fetchedAt arrives the date lands from 1.3× on recoil while the tag cools and the control folds away; when now moves every age rolls to its new reading on snap. The control is a real button with aria-busy, so Tab reaches each stale source and Enter or Space re-fetches it.

KQ-775 · FRESHNESS/TAG

Basinworks quarterly letter
basinworks.example2 Jun 2026
stale, fetched 2 Jun 2026, 3 months ago. 99 days old.
Coldbrook yard notes
coldbrook.example7 Sep 2026
fresh, fetched 7 Sep 2026, 2 days ago. 2 days old.
Fieldline rota export
fieldline.example30 Aug 2026
fresh, fetched 30 Aug 2026, 1 week ago. 10 days old.
Waylight fare table
waylight.example14 Mar 2026
stale, fetched 14 Mar 2026, 5 months ago. 179 days old.

9 Sep 2026 · 2 stale of 4

Install

One command — the source lands in your repo. Or copy it from the Code tab.

$ pnpm dlx shadcn@latest add @kinetiq/freshness-tag

Props

sources: FreshSource[]; default —; Sources with id, title, site and fetchedAt as an ISO date or date-time.
now: string | number; default —; The moment ages are measured from — an ISO date or epoch milliseconds; pass it from an effect or the server, never from render.
staleAfterDays: number; default 30; Age in days at which a source turns amber and offers a re-fetch.
fetching: string[]; default []; Ids the host is re-fetching right now; their controls turn and their tags read fetching.
onRefetch: (id: string) => void; default —; Fires from the press on a stale source's re-fetch control.
formatDate: (iso: string) => string; default 9 Sep 2026; Formats a fetched date for the row and the descriptions; the default uses a fixed month table so server and browser agree.
label: string; default —; Names the list for assistive technology.

Prop	Type	Default	Description
sources	FreshSource[]	—	Sources with id, title, site and fetchedAt as an ISO date or date-time.
now	string \| number	—	The moment ages are measured from — an ISO date or epoch milliseconds; pass it from an effect or the server, never from render.
staleAfterDays	number	30	Age in days at which a source turns amber and offers a re-fetch.
fetching	string[]	[]	Ids the host is re-fetching right now; their controls turn and their tags read fetching.
onRefetch	(id: string) => void	—	Fires from the press on a stale source's re-fetch control.
formatDate	(iso: string) => string	9 Sep 2026	Formats a fetched date for the row and the descriptions; the default uses a fixed month table so server and browser agree.
label	string	—	Names the list for assistive technology.