FormattedDateTime

Importing

import { FormattedDateTime } from '@customerio/pluma-components/react';

Usage

The component accepts the date to be formatted in the date prop. This can be a Date instance, a valid time string (one that would be accepted by the Date constructor), or a number - a unix timestamp (in milliseconds).

<FormattedDateTime date="2012-01-30T08:12:34Z" dateTimeFormatOptions={{ timeZone: 'UTC' }} />

The component supports a few predefined formats, which can be selected with the format prop on the component. The available options are:

Putting these together, the component would be invoked like:

<FormattedDateTime date="2012-01-30T08:12:34Z" format="time" dateTimeFormatOptions={{ timeZone: 'UTC' }} />

Internally, the component uses Intl.RelativeTimeFormat to create the formatted strings.

Relative date

The component accepts a withRelativeDateFromNow prop (boolean), which - when enabled - will make the component format the date component of the formatted string as Yesterday, Today, or Tomorrow - if the date is yesterday, today or tomorrow relative to the current time.

<FormattedDateTime
 date={yesterday}
 withRelativeDateFromNow={true}
 format="full_with_time"
/>

Tooltips

When showing dates formatted in a shorter format, it may be helpful to show a tooltip with the full version of the date. The component supports a tooltip, which can be enabled with the withTooltip prop.

Additionally, isTooltipTriggerUnderlined may be set to true, to add an underlined style to the formatted date, to better indicate that it's interactive:

<FormattedDateTime date={now} format="medium" withTooltip={true} isTooltipTriggerUnderlined={true} />

When using the relative date format, the tooltip can be made "smart" and only render when "Yesterday", "Today", or "Tomorrow" is shown:

<FormattedDateTime
 date={now}
 withRelativeDateFromNow={true}
 withTooltipIfRelativelyFormatted={true}
 isTooltipTriggerUnderlined={true}
/>

<FormattedDateTime
 date={inThreeDays}
 withRelativeDateFromNow={true}
 withTooltipIfRelativelyFormatted={true}
 isTooltipTriggerUnderlined={true}
/>

Utilities

Internally, the component uses the formatDateTime utility, which can be imported as

import { formatDateTime } from '@customerio/pluma-components/react/utils/formatted-date-time';

The utility accepts three arguments:

const formatted = formatDateTime(date, format, dateTimeFormatOptions, options);

• date - the date to format
• format - (optional) the format to use for the output string
• dateTimeFormatOptions - (optional) overrides to use for Intl.DateTimeFormat, which is used internally for formatting
• options - (optional) an object with the following properties:
  • withRelativeDateFromNow - controls whether close dates should show as "Yesterday"/"Today"/"Tomorrow"
  • shouldUppercaseFirst - whether the first letter of the formatted string should be uppercased