Examples
Default
By default, a timestamp will display the current date and time based on the current locale if the date prop is not passed in.
Passing the shouldDisplayUTC property will display the UTC date and time instead of the current or passed in locale.
Basic formats
The format of the displayed content can be customized by passing in the dateFormat and/or timeFormat props. Passing in only one of the props will display only the date or time, depending on which prop is passed in. The possible options are "full", "long", "medium", and "short".
You can also pass in the displaySuffix prop to display a custom suffix at the end of the displayed content. This will not override a timezone that is already displayed from the applied time format.
Custom format
The format of the displayed content can be further customized by passing in the customFormat prop. Read datetime format options for a list of options that can be passed in.
Default tooltip
To render a tooltip that displays the timestamp content as a UTC time, you can pass in the tooltip prop with a variant of "default". The format of the default tooltip content will match the format of the timestamp content.
You can customize the suffix of this default tooltip variant by passing in suffix to the tooltip prop.
Custom content
To display custom content, such as a relative time or prefacing text, you can pass in content to the children prop.
When also rendering a default tooltip with the tooltip prop, you can pass in the dateFormat and/or timeFormat props to customize the tooltip content without affecting the custom timestamp content.
Custom tooltip
By passing in variant="custom" and content to the tooltip prop, you can display custom content within the timestamp's tooltip.
Props
Timestamp
| Name | Type | Default | Description |
|---|---|---|---|
| children | React.ReactNode | Displays custom content inside the timestamp, such as a relative time. This prop will override the default content that is displayed. Custom content will not be affected by any props that format or add to displayed content. | |
| className | string | Class to add to the outer span. | |
| customFormat | { [key: string]: string } | Applies custom formatting to the displayed date and/or time. Passing this prop in will override the dateFormat and timeFormat props. | |
| date | Date | Determines the default content that is displayed inside the timestamp and the value of the inner time element's datetime attribute. | |
| dateFormat | 'full' | 'long' | 'medium' | 'short' | Determines the format of the displayed date in the timestamp and UTC tooltip. Examples: "Full" => Tuesday, August 9, 2022; "Long" => August 9, 2022; "Medium" => Aug 9, 2022; "Short" => 8/9/22 | |
| displaySuffix | string | '' | Applies a custom suffix to the displayed content, usually after the time, such as a custom time zone. |
| is12Hour | boolean | Flag for displaying the time in a 12 hour format. If this prop is not passed in, the hour format will be based on the locale prop's value. | |
| locale | string | Determines which locale to use in the displayed content. Defaults to the current locale when this prop is not passed in. For more information about locale's: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#Locale_identification_and_negotiation | |
| shouldDisplayUTC | boolean | Flag indicating whether the default content should be displayed as a UTC string instead of a local string. | |
| timeFormat | 'full' | 'long' | 'medium' | 'short' | Determines the format of the displayed time in the timestamp and UTC tooltip. Examples: "Full" => 11:25:00 AM Eastern Daylight Time "Long" => 11:25:00 AM EDT "Medium" => 11:25:00 AM "Short" => 11:25 AM | |
| tooltip | TimestampTooltip | Adds a tooltip to the timestamp. |
TimestampTooltip
| Name | Type | Default | Description |
|---|---|---|---|
| variantrequired | 'default' | 'custom' | The variant of the tooltip. The "default" variant displays the date passed into the timestamp's date prop as a UTC string. | |
| content | React.ReactNode | Content displayed in the tooltip when using the "custom" variant. | |
| suffix | string | A custom suffix to apply to a "default" variant tooltip. | |
| tooltipProps | any | Additional props passed to the tooltip. |
CSS variables
| Expand or collapse column | Selector | Variable | Value |
|---|
