FormattedRelativeTime

Importing

import { FormattedRelativeTime } 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).

By default, that date will be compared to the current date and time.

<FormattedRelativeTime date={tenSecondsAgo} />

The component will automatically update the displayed value as time passes. This can be disabled by setting the shouldUpdateCurrentTime prop to false.

The component also handles future dates correctly:

<FormattedRelativeTime date={inFiveAndAHalfDays} />

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

Automatic absolute formatting

If the difference between dates is more than 30 days, the component will fall back to showing an absolutely formatted date, as the relative formatting becomes less useful and more mental work when the time periods get longer.

<FormattedRelativeTime date={twentyNineDaysAgo} />

<FormattedRelativeTime date={thirtyOneDaysAgo} />

The "absolute" format is, by default, the medium format used by the FormattedDateTime component. The format can be customized by passing another format name as the formatOptionWhenAbsolute prop:

<FormattedRelativeTime
 date={thirtyOneDaysAgo}
 formatOptionWhenAbsolute="full_with_time"
/>

The time difference, after which absolute formatting is used, can be customized with the absoluteFormatDiffCutoff prop. It expects a number of seconds as the value.

Tooltips

The component can optionally show a tooltip, with the fully formatted date and time, 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:

<FormattedRelativeTime
 date={tenSecondsAgo}
 withTooltip={true}
 isTooltipTriggerUnderlined={true}
/>

The tooltip can be made "smart" by enabling the withTooltipIfRelativelyFormatted prop. This will automatically only enable the tooltip if the date is in the "relative" format: if the time difference is above the "absolute cutoff", the tooltip won't show.

<FormattedRelativeTime
 date={tenSecondsAgo}
 withTooltipIfRelativelyFormatted={true}
 isTooltipTriggerUnderlined={true}
/>

<FormattedRelativeTime
 date={thirtyOneDaysAgo}
 formatOptionWhenAbsolute="full_with_time"
 withTooltipIfRelativelyFormatted={true}
 isTooltipTriggerUnderlined={true}
/>

Utilities

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

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

The utility accepts three arguments:

const formatted = formatRelativeTime(date, referenceDate, options);

• date - the date to format
• referenceDate - the date to compare to (defaults to now if not provided)
• options - (optional) an object with the following properties:
  • absoluteFormatDiffCutoff - the time difference, after which absolute formatting is used
  • formatOptionWhenAbsolute - the format to use for absolute dates
  • shouldUppercaseFirst - whether the first letter of the formatted string should be uppercased