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
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.
<div class="flex flex-col gap-small">
<div>
Start separator
<forge-timestamp datetime="2024-06-15T14:30:45" separator="start">
</forge-timestamp>
</div>
<div>
<forge-timestamp datetime="2024-06-15T14:30:45" separator="end">
</forge-timestamp>
End separator
</div>
<div>
No separator
<forge-timestamp datetime="2024-06-15T14:30:45" separator="none">
</forge-timestamp>
</div>
</div>Timestamps display formatted dates and times.
import "@tylertech/forge/timestamp";| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
datetime | datetime | Date | string | '' | The date/time value to display. Accepts a Date object, an ISO string, or an HTML `<time>` element's `datetime` attribute value. |
format | format | string | '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. |
locale | locale | string | navigator.language | The locale to use for formatting. |
separator | separator | TimeStampSeparatorPosition | 'none' | Places a separator dot before or after the timestamp. |
| Name | Description |
|---|---|
(default) | The default slot. Content in this slot will be displayed instead of the formatted date/time. |
| Name | Description |
|---|---|
::part(root) | The root element. |
| Name | Description |
|---|---|
--forge-timestamp-color | The color of the timestamp text. |
--forge-timestamp-margin-block | The 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.