Timestamp

Timestamps display a formatted, localized date, time, or duration value using the native time element.

Overview

Timestamps display a time, date, or other duration, in a specifically formatted style to be used when referencing a date or time in your UI. It’s primarily used with the timeline component, but it can be used anywhere a data or time is needed. When referencing a date or time, use the timestamp component to keep your dates and times displayed in the same way through out your applications.

Usage

forge-timestamp renders a <time> element from a datetime value, formatted through format (a CLDR date/time pattern), locale, and separator. Set datetime to a Date, a date-convertible string, or any value the native <time> element’s datetime attribute accepts; that value drives both the accessible meaning and, for full dates, the automatic formatting. A dateless time, timezone offset, or duration value is used as-is for accessibility but isn’t auto-formatted — pass custom content in the default slot for those cases. Use it anywhere a date or time needs consistent, localized formatting, including inside a timeline item.

Rules

Do
Always set datetime to the underlying date/time value, even when the visible format only shows part of it.Use a CLDR format string in format rather than pre-formatting the value yourself.Set locale explicitly when a timestamp shouldn't follow the user's browser locale.
Don't
Don't rely on automatic formatting for a dateless time, timezone offset, or duration — supply custom content in the default slot instead.Don't hardcode a display string when the value is a real date — let format handle it so it stays localized.

Formatting

Set format to any valid CLDR date/time pattern to control how the timestamp displays.

<!-- Hour and minute -->
<forge-timestamp datetime="2024-03-15T14:30:00" format="HH:mm"></forge-timestamp>

<!-- Day and month -->
<forge-timestamp datetime="2024-03-15T14:30:00" format="MMMM dd"></forge-timestamp>

<!-- With additional text -->
<forge-timestamp datetime="2024-03-15T14:30:00" format="'Today' • MMMM dd, yyyy"></forge-timestamp>

Locale

Set locale to format the timestamp for a specific locale instead of following the user’s browser locale.

<forge-timestamp datetime="2024-03-15T14:30:00" locale="fr-FR"></forge-timestamp>

Separators

Set separator to start or end to place a dot before or after the timestamp, visually separating it from adjacent inline content. The default is none.

Timestamps with a separator dot before, after, or not at all, next to other inline content.

Timestamps display formatted dates and times.

import "@tylertech/forge/timestamp";
Properties
PropertyAttributeTypeDefaultDescription
datetimedatetimeDate | string''The date/time value to display. Accepts a Date object, an ISO string, or an HTML `<time>` element's `datetime` attribute value.
formatformatstring'MM/dd/yyyy'The CLDR format string for displaying the date. Only applies when the value of `datetime` is a valid Date object or date-convertible string. Any other `datetime` value will be displayed as-is unless a custom element is slotted.
localelocalestringnavigator.languageThe locale to use for formatting.
separatorseparatorTimeStampSeparatorPosition'none'Places a separator dot before or after the timestamp.
Slots
NameDescription
(default)The default slot. Content in this slot will be displayed instead of the formatted date/time.
CSS Parts
NameDescription
::part(root)The root element.
CSS Custom Properties
NameDescription
--forge-timestamp-colorThe color of the timestamp text.
--forge-timestamp-margin-blockThe margin around the timestamp on the block axis.

Accessible value

forge-timestamp renders a native <time> element, which already carries semantic meaning for assistive technology. Set datetime to the real underlying value — screen readers and other assistive technology read from that attribute, not from the formatted text, to announce the timestamp accurately.

Type to search the docs.

NavigateSelectClose
Loading Forge chat…