Time & Keyboard
Relative and absolute timestamps, and platform-aware keyboard shortcut key caps.
Components in this category
Displays a time relative to now ('5 minutes ago').
TimestampFormatted absolute timestamp.
KeyboardShortcutDisplays a keyboard shortcut as styled Kbd keycaps.
RelativeTime
RelativeTime displays a time relative to now: "3m ago", "in 2 hr", "just now". It renders a real <time datetime> element with the absolute value in title, so hovering (and copying) still gives the precise instant. The refresh interval scales with the age shown: a 30-second-old row ticks every 15s, a week-old row every 10 minutes.
| Prop | Type | Default | Description |
|---|---|---|---|
date | Date | — | The moment to display relative to now. |
format | RelativeStyle | "narrow" | "narrow" (log-table format: "3m"), "short" ("3 min ago"), or "long" ("3 minutes ago"). |
live | boolean | true | Stop re-rendering as the clock moves. |
showTitle | boolean | true | Absolute time tooltip on hover. |
cutoffMs | number | — | Past this age, show the absolute date instead. |
SSR behavior
RelativeTime uses useHydrated() internally. On the server and during the first client render, it renders an absolute timestamp in UTC and a fixed locale so the markup is deterministic. After hydration it switches to relative text using the reader's real clock and timezone. The initial trees match without hydration-warning suppression.
The formatRelativeTime helper is exported separately for formatting relative time strings without rendering a component.
import { RelativeTime, formatRelativeTime } from "@solarius/onset";
import type { RelativeStyle } from "@solarius/onset";
<RelativeTime date={new Date()} format="narrow" />
<RelativeTime date={someDate} format="short" live={false} />
// The helper for formatting strings directly:
formatRelativeTime(new Date(), new Date(), "long"); // "just now"Timestamp
Timestamp displays a formatted absolute timestamp, the fixed counterpart to RelativeTime. Defaults to mono text (tabular figures) so stacked rows align. On hover it shows the relative time as a title.
| Prop | Type | Default | Description |
|---|---|---|---|
date | Date | — | The moment to display. |
seconds | boolean | true | Include seconds in the output. |
year | boolean | — | Include the year. Defaults to true. |
mono | boolean | true | Monospace + tabular figures for alignment. |
relativeTitle | boolean | true | Show relative time on hover. |
SSR behavior
Timestamp and RelativeTime render UTC on the server and the first client render. After hydration, they update to the local timezone through useHydrated().
The formatTimestamp and formatDate helpers are exported separately for formatting timestamp strings without rendering a component.
import { Timestamp, formatTimestamp, formatDate } from "@solarius/onset";
<Timestamp date={new Date()} />
<Timestamp date={someDate} seconds={false} year={false} />
// Helpers for formatting strings directly:
formatTimestamp(new Date()); // "Jan 13, 2026, 09:41:07"
formatTimestamp(new Date(), { seconds: false, year: false }); // "Jan 13, 09:41"KeyboardShortcut
KeyboardShortcut renders a keyboard shortcut as styled Kbd key caps. Use "mod" for the primary modifier rather than hardcoding ⌘ or Ctrl; it resolves per platform at render time. Pairs with CommandPalette and DropdownMenu, where every action should advertise its accelerator.
| Prop | Type | Default | Description |
|---|---|---|---|
keys | string | — | Shortcut string, e.g. "mod+k", "mod+shift+/", "ctrl+alt+delete". "+" separates keys. |
platform | "mac" | "win" | — | Force a platform instead of sniffing. Pass explicitly to avoid the hydration swap. |
size | "sm" | "md" | "md" | Key cap size. |
joined | boolean | — | Renders one merged cap ("⌘K") instead of separate keys. |
subtle | boolean | — | Dim styling, for shortcuts inside an already-highlighted row. |
SSR behavior
Platform sniffing cannot run until after hydration: the server has no way to know the visitor's OS. So KeyboardShortcut renders the non-Mac form (Ctrl) on the server and first client pass, then swaps to the real platform after hydration. Pass platform explicitly to opt out of the swap entirely.
The parseShortcut helper is exported for splitting a shortcut string into display keys without rendering a component.
import { KeyboardShortcut, parseShortcut } from "@solarius/onset";
<KeyboardShortcut keys="mod+k" />
<KeyboardShortcut keys="mod+shift+/" joined />
<KeyboardShortcut keys="ctrl+alt+delete" size="sm" subtle />
// Force platform to avoid the hydration swap:
<KeyboardShortcut keys="mod+k" platform="mac" />
// Parse a shortcut string into display keys:
parseShortcut("mod+shift+k", true); // ["⌘", "⇧", "K"]
parseShortcut("mod+shift+k", false); // ["Ctrl", "Shift", "K"]