Components v5.0.0 — 18 new components, Light DOM APIs, and updates across forms, filters, data display, and navigation.See what's new

ClickorKeyboard shortcut Alt + L

Dragto resize

Nord Design System SearchDeveloperDeveloperGetting startedUsing Web ComponentsWebfontsCDNLocalizationCSS Framework Legacy ESLint PluginWorking with AIFAQDesignDesignGetting startedFoundationsAccessibilityColor SystemColor UtilitiesPrinciplesFigma ToolkitGridIconographyNamingNordhealth BrandTypographyThemesBrand assetsToolsComponentsComponentsAccordion New Aside New Autocomplete New AvatarBadgeBanner Updated ButtonButton GroupCalendar Updated Card Updated Chart New Checkbox Updated Collapsible New Combobox New Command MenuDate Picker Updated Date Range Picker New DividerDrawer Updated DropdownEmpty StateField New FieldsetFilter Bar New FooterHeaderIconInput Updated Input Group New Item New Kbd New LayoutMessageMeter New Modal Updated NavigationNotificationNumber Field New Otp Field New Outline New Overflow List New Pagination New Popout Updated ProgressProgress BarQrcodeRadio Updated Range Updated Resizable New Rich Text Editor New Scroll Area New Segmented ControlSelect Updated SkeletonSpinnerStackTabTableTagTextarea Updated Time Picker New Timestamp New ToastToggle Updated TooltipTop BarTruncate New Visually HiddenDesign TokensDesign TokensTailwind CSSTailwind CSSBlocksBlocksTemplatesTemplatesIconsIconsPlaygroundPlaygroundLatest UpdatesLatest UpdatesChangelogChangelogMigration guidesMigration guides
GitHub

Clickto expandKeyboard shortcut Alt + L

Timestamp New Alpha Light DOM & Tailwind

Open in Storybook

Presents an instant as localized, system, relative, or automatically selected date-time text.

This component is considered alpha. We're still finalising the API, so it may include a breaking change at any time — use it at your own risk.
Loading...

Usage

Timestamp displays an ISO 8601 instant with native <time> semantics. It can use localized absolute text, stable system text, or relative language such as “2 hours ago”.

Importing the component registers its custom element:

import "@nordhealth/components/lib/Timestamp"

Set the HTML value attribute to an ISO 8601 string. When assigning through JavaScript, a finite numeric .value is interpreted as Unix seconds. Use auto when recent values should be relative and older values should settle into an absolute date and time:

Composition

Timestamp renders a native <time> element in Light DOM. The value identifies the instant, while format, time-zone, lang, live, and tooltip properties determine how that instant is presented without changing its machine-readable value.

Accepted ISO calendar profile

Timestamp accepts calendar dates with a four-digit year or a signed six-digit expanded year: YYYY-MM-DD or ±YYYYYY-MM-DD. Append THH:mm, optional :ss, optional 1–9 digit fractional seconds, and optional Z or ±HH:mm offset for a date-time. T and Z are case-insensitive. Months are 01–12, days must exist in the Gregorian calendar, hours are 00–23, minutes and seconds are 00–59, and offsets are 00:00–23:59. 24:00 is valid only when minutes, seconds, and fractions are zero; -000000, week dates, ordinal dates, basic forms, prose dates, space separators, leap seconds, and other invalid fields are rejected.

Date-only values mean midnight UTC. A date-time without Z or an offset uses the runtime’s local timezone. Explicit offsets determine the instant, while time-zone affects formatting only. JavaScript Date stores milliseconds, so accepted fractional digits after the first three are truncated.

Examples

Formats

Timestamp supports relative, auto, date, date-time, time, system-date, system-date-time, and system-time. Localized formats follow the effective host or document language; system formats use stable, zero-padded astronomical years. Localized BCE values include an era so year zero and earlier dates remain unambiguous.

Relative boundaries

Relative output works for past and future values without rounding across the next unit. Units change at 60 seconds, 60 minutes, 24 hours, 30 days, and 365 days. Future values within 30 seconds are treated as clock skew and displayed as the present.

Relative examples sample one current time when each story renders, so they remain meaningful in normal Storybook use. The visual-regression runner freezes that render-time clock to keep screenshots deterministic.

Automatic threshold

auto-threshold is the maximum distance in seconds for relative output. Its default is 604800 seconds (one week). Outside the threshold, auto uses date-time.

Timezones

Use time-zone with an IANA timezone such as Europe/Helsinki. Add show-time-zone to localized formats when the short timezone name is useful context.

Localization

Localized formats, relative phrases, and accessible full detail follow the host lang, or the document lang when the component has no override. Native Intl localization works even when Nord component translations are not registered for that language, and changing lang after connection updates the output.

Live relative time

Add live to update at the next meaningful relative-time boundary. Timestamp pauses while the document is hidden and stops timers when disconnected or when automatic output becomes absolute.

Full detail tooltip

Relative output always exposes the full localized absolute value as its accessible name. show-tooltip makes that same detail available visually on hover or keyboard focus without using the HTML title attribute.

Invalid values

Missing, malformed, non-finite, or out-of-range values render no <time> content and do not create a live timer.

Accessibility

  • Timestamp renders a native <time datetime="…"> element in light DOM so its machine-readable instant remains available to browsers and assistive technology.
  • Relative output has a localized full date and time as its accessible name. Tooltip-enabled relative values become keyboard focusable; absolute and tooltip-free values do not add a tab stop.
  • Avoid relying on relative text alone when an exact instant is important. Enable the tooltip or choose an absolute format.

API reference

Timestamp

Timestamp presents an instant as localized, stable system, relative, or automatically selected text while retaining native date-time semantics.

<nord-timestamp></nord-timestamp>

Props

PropertyAttribute Description TypeDefault
valuevalueThe instant to display. Strings use Timestamp's documented ISO calendar profile; finite numbers assigned through JavaScript are Unix seconds.string | number | undefined—
formatformatThe display format. Automatic format uses relative text near the instant.TimestampFormat'auto'
autoThresholdauto-thresholdMaximum age, in seconds, for relative output in automatic format.unknownDEFAULT_AUTO_THRESHOLD
showTooltipshow-tooltipShows the full absolute timestamp in a Nord Tooltip for relative output.booleanfalse
showTimeZoneshow-time-zoneAdds a short timezone name to localized formats which include time.booleanfalse
timeZonetime-zoneIANA timezone used for formatting. Defaults to the runtime timezone.string | undefined—
liveliveUpdates relative and automatic output at meaningful display boundaries.booleanfalse
sizesizeOptional Nord text size. Omit it to inherit the surrounding font size.TimestampSize | undefined—
colorcolorOptional Nord text color.TimestampColor | undefined—
weightweightOptional Nord text weight. Omit it to inherit the surrounding weight.TimestampWeight | undefined—

CSS Properties

CSS Custom Properties provide more fine grain control over component presentation. We advise utilizing existing properties on the component before using these.

PropertyDescriptionDefault
--n-timestamp-colorControls the timestamp text color.var(--n-color-text-weaker)
--n-timestamp-font-sizeControls the timestamp font size. By default it inherits from surrounding text.—
--n-timestamp-font-weightControls the timestamp font weight. By default it inherits from surrounding text.—
Light DOM & Tailwind. This component renders in the light DOM, so you can style it directly with your own CSS or Tailwind utility classes — there is no shadow boundary, and its default styles are low specificity, so your utilities win.
Design guidelinesFor designers

Usage

This section includes guidelines for designers and developers about the usage of this component in different contexts.

Do

  • Use Timestamp for dates and times that need consistent native semantics and localized presentation.
  • Use relative for recent activity, or auto when older values should become a stable date and time.
  • Set lang on the component, or on the document as a fallback, to localize Intl output even when that language has no registered Nord component translation.
  • Enable show-tooltip when people benefit from inspecting the full absolute date and time behind relative text.
  • Use live only when the relative phrase needs to remain current while it is visible.

Don’t

  • Don’t provide prose or locale-specific date strings; use an ISO 8601 value or assign finite Unix seconds through JavaScript.
  • Don’t enable live updates for absolute formats, where the displayed value does not change.
  • Don’t use Timestamp for editable date or time input.

Accepted values

String values use a strict ISO calendar profile: a four-digit year or signed six-digit expanded year, followed by -MM-DD. The date may be followed by THH:mm, optional :ss, optional 1–9 digit fractional seconds, and optional Z or ±HH:mm offset. The T and Z literals are case-insensitive. Months are 01–12, days must exist in the Gregorian calendar, hours are 00–23, minutes and seconds are 00–59, and offsets are 00:00–23:59. 24:00 is accepted only when every smaller field is zero, and the ISO-invalid expanded year -000000 is rejected. Week dates, ordinal dates, basic/unseparated forms, prose dates, space separators, and leap seconds are not accepted.

Date-only strings represent midnight UTC. Date-times without Z or an offset represent local time in the runtime timezone. A supplied offset determines the instant; the component’s time-zone option changes presentation only, never parsing. Fractions beyond milliseconds are accepted and truncated by JavaScript Date precision.