Skip to content

Time

A time in words, relative in rows and exact in detail, plus long dates and durations.

<p>A publication date or a deadline: no time of day, and the same words on a server and in a browser.</p>
<p id="sample-date">Published <time class="cap-time" data-cap="time" data-format="date" datetime="2026-09-12">September 12, 2026</time>. Abstracts due <time class="cap-time" data-cap="time" data-format="date" datetime="2026-11-03">November 3, 2026</time>.</p>

Installation

// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import "capsomer/time.css";
import { enhance } from "capsomer/behavior/time";

enhance();

Usage

<time class="cap-time" data-cap="time" datetime="2026-09-30T13:55:00Z">5 minutes ago</time>

<!-- in the detail -->
<time class="cap-time" data-cap="time" data-format="exact" datetime="2026-09-30T13:02:00Z">September 30, 2026, 1:02 PM UTC</time>

Examples

Durations, as a timecode and in words

<p>How long, not when: an episode's length as a player writes it and as a screen reader should hear it, a wait, a countdown. Drawn by React from the same functions the page imports.</p>
<div data-mount="durations"></div>

Relative with its exact time in a tooltip, and no time at all

<p>For a table that has no detail to show the exact time in. The time takes a tab stop. Drawn by React, inside a paragraph.</p>
<div data-mount="tip"></div>

Live: redrawn every 30 seconds

<p id="sample-live">The improve loop last ran <time class="cap-time" data-cap="time" datetime="2026-09-30T13:59:00Z">at 1:59 PM UTC on September 30, 2026</time>.</p>

React: sent by a server in UTC, then hydrated into your zone

<div id="time-hydrate"></div>

API reference

Time

PropTypeRequiredDoes
atnumber | Date | string | null | undefinedYesMilliseconds, a Date, or a server timestamp (a zoneless one is read as UTC). Null, undefined or an empty string is no time at all: empty says so.
formatTimeFormatRelative in rows; exact (viewer's zone and UTC) in a detail; "date" a long date with no time of day, in UTC, so a server and a browser print the same ("September 12, 2026").
emptyReactNodeWhat to say when there is no time ("never", "Not yet run"). Without it a missing time reads "an unreadable time", as one that cannot be read does.
tipbooleanA relative time with its exact time (the viewer's zone, then UTC) in a tooltip on hover and keyboard focus, for a table that has no detail to show it in. The time takes a tab stop, so use it where each row does not already have one. Drawn as spans, so it sits inside a paragraph.
nownumberA fixed "now", for a report or a test, or the server's now when its clock and the browser's disagree (serverNow). Without it the text refreshes every 30 s.

Functions

FunctionSignatureDoes
parse(iso: string): number
toMs(at: string | number | Date | null | undefined): numberA time as a number of milliseconds: a number, a Date, or a server timestamp (a zoneless one is UTC). NaN for nothing, an empty string or a value that is not a time.
toMsOrNull(at: string | number | Date | null | undefined): number | nullThe same, null where toMs gives NaN, for a caller that tests for "no time" with == null.
calendarDays(t: number, now: number, zone?: string | undefined): numberWhole calendar days from t to now in the zone: 1 is yesterday, -1 tomorrow.
day(t: number, now?: number, zone?: string | undefined): string"September 12", or "September 12, 2025" when the year is not this one: American English, the family's (Dustin, 2026-10-25).
relative(t: number, now?: number, zone?: string | undefined, options?: RelativeOptions): stringRelative, spelled out: "just now", "less than a minute ago", "5 minutes ago", "3 hours ago", "yesterday", "4 days ago", "September 12"; and ahead, "in 3 hours", "tomorrow". Minutes and hours are whole and round down, so "1 hour ago" means at least an hour. The unit words are Intl.RelativeTimeFormat's.
utc(t: number): stringThe Portal's compact UTC form, for logs and ids: "2026-09-30 13:02Z".
formatDate(at: string | number | Date | null | undefined, options?: FormatDateOptions): string | nullA date, American English (the family's), from a number, a Date or a timestamp string. Null for a value that is not a time ("Invalid Date" is never shown; the caller says what goes in its place). Intl.DateTimeFormat does the words: dateStyle and timeStyle (MDN: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat).
dateRange(start: string | number | Date | null | undefined, end: string | number | Date | null | undefined, options?: Pick<FormatDateOptions, "style" | "zone">): string | nullA meeting's dates: "May 1, 2026", "May 1, 2026 to May 2, 2026", or null with no dates. One date when both are the same moment.
timecode(ms: number | null | undefined, options?: { hours?: "auto" | "always" | undefined; }): stringA duration as a player's timecode writes it: "4:05", "1:02:03". With hours: "always", the form a feed wants for <itunes:duration>: "00:04:05", "01:02:03". Negative, missing or NaN is zero.
duration(ms: number | null | undefined, options?: DurationOptions): stringA duration in words, for a screen reader or a sentence: "3 minutes, 12 seconds", "1 hour, 2 minutes, 3 seconds", "0 seconds". Units that are zero are left out.
span(ms: number | null | undefined): stringA rough duration to the largest unit, rounded down, for "waiting 3 hours" and "oldest 2 days": "less than a minute", "5 minutes", "3 hours", "2 days". The spelled-out form of a compact "3.2h".
until(t: number, now?: number): stringHow soon something scheduled fires, spelled out: "due now" once the moment has passed, then "in 5 minutes", "in 3 hours, 20 minutes" (the hour form carries the minutes, since "in 3 hours" hides up to 59 of them), and "in 2 days" (a day or more drops the hours, which would be noise).
zoneName(t: number, zone?: string | undefined): stringThe zone's short name as an American reader knows it: "CST", "CDT", "EST", "PDT". en-US has names only for the American zones and writes "GMT+1" for the rest, so a zone it has no name for takes the British one when there is one ("BST", "CEST"), else the offset.
exactParts(t: number, zone?: string | undefined): { local: string; utc: string | null; }Exact, in the viewer's zone with UTC beside it, in two parts so the UTC part can be kept whole on a line (the Portal's .when .faint { white-space: nowrap }): the local time, and "(1:02 PM UTC)". UTC's date is added when it differs from the local one; a viewer in UTC sees one time and no second part.
exact(t: number, zone?: string | undefined): string"November 3, 2026, 8:00 AM CST (2:00 PM UTC)".
text(t: number, format: TimeFormat, now?: number, zone?: string | undefined): stringThe text a <time class="cap-time"> shows.
serverNow(clientNow: number, skew: number, newestServerRead: number): numberThe page's "now" for relative times when the browser's clock and the server's disagree: the browser's clock moved onto the server's by the skew measured when the data arrived, and never earlier than the newest time a server read reported. Otherwise a row written after the page's last tick, or on a server whose clock runs ahead of the browser's, reads "in less than a minute" for something that has just happened. From the Portal's lib/format.ts (portalNow). Pass it as a React now, or give setClock a function that returns it.
setClock(fn: (() => number) | null): voidReplaces the clock the plain behavior module reads (the default is Date.now), and redraws. setClock(null) puts it back.
nowFor(el: Element): { now: number; frozen: boolean; }"now" for an element: a frozen data-cap-now on it or an ancestor (specimens, tests, printed reports), else the clock.
draw(el: HTMLElement): void
enhance(root?: ParentNode): () => voidAttaches to every [data-cap="time"] under root not yet attached: writes its text, and keeps relative times fresh every 30 seconds with one shared timer. Returns a function that detaches.
knownZone(zone: string | null | undefined): stringA zone name the browser's Intl knows, else "UTC": a zone from a form or from Cloudflare's request.cf.timezone can be missing or unknown, and Intl throws on an unknown one. From Carrel (lib/writing/progress.ts).
laterUntil(now: number | Date, zone: string | null | undefined, hour?: number): stringWhen Later brings something back: hour (8 am) on the next calendar day in the person's zone (UTC when the zone is unknown), as an ISO instant. The wall-clock time is found by correcting a first guess by the zone's offset, twice, so a change to or from summer time overnight still lands on 8 am. From Carrel's Home (lib/desk.server.ts, laterUntil).
two(n: number): stringA number as two digits, "07".

Parts and data attributes

ClassIs
.cap-timethe root
.cap-time-tipa part
.cap-time-utca part
AttributeValues
data-formatdate exact
data-tonetext

Accessibility

KeyDoes
NoneA time is text. The exact time is reached by opening the row's detail, with the row's own keys.
  • The text is the accessible text; it is a sentence part ("deployed 5 minutes ago") and reads as one.
  • A relative time is --muted (4.5:1 on every surface, the selected row included); an exact time is --text and its UTC part --muted. data-tone="text" gives a relative time the text color.
  • The exact form names the zone ("CST") and gives UTC, so a time read aloud or copied is not ambiguous.