Skip to content

Freshness

How old the data on screen is, with a ring counting down to the next read.

<div class="cap-fresh" id="fr-fresh" title="Live data read 12:04 UTC. Site data from the watcher pass at 12:00 UTC (every 5 min).">
  <svg class="cap-fresh-ring" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><circle class="cap-fresh-ring-track" cx="8" cy="8" r="6.5" fill="none" stroke-width="2"></circle><circle class="cap-fresh-ring-left" cx="8" cy="8" r="6.5" fill="none" stroke-width="2" stroke-dasharray="28.59 40.84" transform="rotate(-90 8 8)" stroke-linecap="round"></circle></svg>
  <span class="cap-fresh-text">Updated <b>a minute ago</b></span>
  <span class="cap-fresh-more">· sites from pass 4 minutes ago</span>
</div>

Installation

// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import "capsomer/freshness.css";
import { shareLeft, ringDash } from "capsomer/behavior/freshness";

Usage

<div class="cap-fresh" title="Live data read 12:04 UTC.">   <!-- data-stale when stale -->
  <svg class="cap-fresh-ring" viewBox="0 0 16 16" aria-hidden="true" focusable="false">...</svg>
  <span class="cap-fresh-text">Updated <b>2 minutes ago</b></span>
  <span class="cap-fresh-more">· sites from pass 4 minutes ago</span>
</div>

Examples

Stale

<div class="cap-fresh" id="fr-stale" data-stale title="Stale after 10 min.">
  <svg class="cap-fresh-ring" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><circle class="cap-fresh-ring-track" cx="8" cy="8" r="6.5" fill="none" stroke-width="2"></circle><circle class="cap-fresh-ring-left" cx="8" cy="8" r="6.5" fill="none" stroke-width="2" stroke-dasharray="8.17 40.84" transform="rotate(-90 8 8)" stroke-linecap="round"></circle></svg>
  <span class="cap-fresh-stale"><svg class="cap-status-glyph" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><path fill="currentColor" fill-rule="evenodd" d="M8 1.2 15.4 14H.6zM7.3 6h1.4v4H7.3zM7.3 11h1.4v1.4H7.3z"/></svg>Stale</span>
  <span class="cap-fresh-text">Updated <b>14 minutes ago</b></span>
  <span class="cap-fresh-more">· no watcher pass for 14 minutes</span>
</div>

A short line cuts the second clause

<div style="max-inline-size: 16rem">
  <div class="cap-fresh" id="fr-short">
    <svg class="cap-fresh-ring" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><circle class="cap-fresh-ring-track" cx="8" cy="8" r="6.5" fill="none" stroke-width="2"></circle><circle class="cap-fresh-ring-left" cx="8" cy="8" r="6.5" fill="none" stroke-width="2" stroke-dasharray="20.42 40.84" transform="rotate(-90 8 8)" stroke-linecap="round"></circle></svg>
    <span class="cap-fresh-text">Updated <b>just now</b></span>
    <span class="cap-fresh-more">· sites from pass 2 minutes ago</span>
  </div>
</div>

Reading, before the first answer

<div class="cap-fresh" role="status" aria-live="polite"><span class="cap-fresh-text">Reading the feed...</span></div>

API reference

Freshness

PropTypeRequiredDoes
updatedReactNodeHow old the data is, already in words ("2 minutes ago"), set in bold.
moreReactNodeA second clause after "·", dropped first when the line is short ("sites from pass 4 min ago").
sharenumberThe share (0 to 1) of the interval left until the next read; leave out for no ring.
stalebooleanThe data is older than it should be: the line turns to warning, led by the warning glyph and staleLabel ("Stale"), so the state is never color alone.
staleLabelReactNode
titlestringThe full times, for the title (hover) text.
pendingReactNodeWhile there is nothing to show yet ("Reading the feed..."): a polite status line instead.

FreshRing

PropTypeRequiredDoes
sharenumberYes

Functions

FunctionSignatureDoes
shareLeft(nextAt: number, now: number, intervalMs: number): numberThe share (0 to 1) of intervalMs left until nextAt, read at now.
ringDash(share: number): string

Parts and data attributes

ClassIs
.cap-freshthe root
.cap-fresh-morea part
.cap-fresh-ringa part
.cap-fresh-ring-lefta part
.cap-fresh-ring-tracka part
.cap-fresh-stalea part
.cap-fresh-texta part
AttributeValues
data-stalepresent or absent

Accessibility

None: it holds no control.

  • The ring is aria-hidden; the line is plain text.
  • The muted text and the bold age reach 4.5:1, and so does the warning color (checked in the spec).
  • In forced colors the ring's arc is drawn in CanvasText.