Date utilities

Import

import {
  formatDateAndTime,
  formatMachineReadableDateTime,
  formatRelativeDateTime,
} from '@contentful/f36-components';
// or
import {
  formatDateAndTime,
  formatMachineReadableDateTime,
  formatRelativeDateTime,
} from '@contentful/f36-datetime';

formatDateAndTime

This function will return a formatted string of any date that is passed as the first argument of the function. It allows 4 different formats that can be chosen by passing one of the format options as a second argument of the function:

If no format is passed to the function, it will return a string with the full format

Examples

Tue, 17 Aug 2021 at 3:45 PMWed, 26 Mar 2025 at 5:34 PMTue, 17 Aug 2021 at 10:45 PM
Hide code
function FormatDateAndTimeExample() {
  return (
    <Stack flexDirection="column">
      {/* passing a Timestamp as an ISOString */}
      <Text>{formatDateAndTime('2021-08-17T15:45')}</Text>
      {/* passing a JS Date */}
      <Text>{formatDateAndTime(new Date())}</Text>
      {/* passing a Unix Epoch in milliseconds */}
      <Text>{formatDateAndTime(1629240300000)}</Text>
    </Stack>
  );
}
function FormatDateAndTimeExample() {
  return (
    <Stack flexDirection="column">
      {/* passing a Timestamp as an ISOString */}
      <Text>{formatDateAndTime('2021-08-17T15:45')}</Text>
      {/* passing a JS Date */}
      <Text>{formatDateAndTime(new Date())}</Text>
      {/* passing a Unix Epoch in milliseconds */}
      <Text>{formatDateAndTime(1629240300000)}</Text>
    </Stack>
  );
}
Open in Playground

Different formats

Tue, 17 Aug 2021 at 3:45:34 PM17 Aug 20213:45 PMTue, 17 Aug
Hide code
function DifferentFormatsExample() {
  return (
    <Stack flexDirection="column">
      {/* With `fullWithSeconds` format */}
      <Text>{formatDateAndTime('2021-08-17T15:45:34', 'fullWithSeconds')}</Text>
      {/* With `day` format */}
      <Text>{formatDateAndTime('2021-08-17T15:45:34', 'day')}</Text>
      {/* With `time` format */}
      <Text>{formatDateAndTime('2021-08-17T15:45:34', 'time')}</Text>
      {/* With `weekday` format */}
      <Text>{formatDateAndTime('2021-08-17T15:45:34', 'weekday')}</Text>
    </Stack>
  );
}
function DifferentFormatsExample() {
  return (
    <Stack flexDirection="column">
      {/* With `fullWithSeconds` format */}
      <Text>{formatDateAndTime('2021-08-17T15:45:34', 'fullWithSeconds')}</Text>
      {/* With `day` format */}
      <Text>{formatDateAndTime('2021-08-17T15:45:34', 'day')}</Text>
      {/* With `time` format */}
      <Text>{formatDateAndTime('2021-08-17T15:45:34', 'time')}</Text>
      {/* With `weekday` format */}
      <Text>{formatDateAndTime('2021-08-17T15:45:34', 'weekday')}</Text>
    </Stack>
  );
}
Open in Playground

formatMachineReadableDateTime

This function will return a machine-readable date string that should be passed to the datetime attribute of a <time> tag. It allows four different formats that can be chosen by passing one of the format options as a second argument to the function:

If no format is passed to the function, it will return a string with the full format

Examples

2021-08-17T15:45:00.000Z2025-03-26T17:34:14.107Z2021-08-17T22:45:00.000Z
Hide code
function FormatMachineReadableDateTimeExample() {
  return (
    <Stack flexDirection="column">
      {/* passing a Timestamp as an ISOString */}
      <Text>{formatMachineReadableDateTime('2021-08-17T15:45')}</Text>
      {/* passing a JS Date */}
      <Text>{formatMachineReadableDateTime(new Date())}</Text>
      {/* passing a Unix Epoch in milliseconds */}
      <Text>{formatMachineReadableDateTime(1629240300000)}</Text>
    </Stack>
  );
}
function FormatMachineReadableDateTimeExample() {
  return (
    <Stack flexDirection="column">
      {/* passing a Timestamp as an ISOString */}
      <Text>{formatMachineReadableDateTime('2021-08-17T15:45')}</Text>
      {/* passing a JS Date */}
      <Text>{formatMachineReadableDateTime(new Date())}</Text>
      {/* passing a Unix Epoch in milliseconds */}
      <Text>{formatMachineReadableDateTime(1629240300000)}</Text>
    </Stack>
  );
}
Open in Playground

Different formats

2021-08-1715:45:00.00008-17
Hide code
function DifferentFormatMachineReadableDateTimeExample() {
  return (
    <Stack flexDirection="column">
      {/* With `day` format */}
      <Text>{formatMachineReadableDateTime('2021-08-17T15:45', 'day')}</Text>
      {/* With `time` format */}
      <Text>{formatMachineReadableDateTime('2021-08-17T15:45', 'time')}</Text>
      {/* With `weekday` format */}
      <Text>
        {formatMachineReadableDateTime('2021-08-17T15:45', 'weekday')}
      </Text>
    </Stack>
  );
}
function DifferentFormatMachineReadableDateTimeExample() {
  return (
    <Stack flexDirection="column">
      {/* With `day` format */}
      <Text>{formatMachineReadableDateTime('2021-08-17T15:45', 'day')}</Text>
      {/* With `time` format */}
      <Text>{formatMachineReadableDateTime('2021-08-17T15:45', 'time')}</Text>
      {/* With `weekday` format */}
      <Text>
        {formatMachineReadableDateTime('2021-08-17T15:45', 'weekday')}
      </Text>
    </Stack>
  );
}
Open in Playground

formatRelativeDateTime

This function will return a relative date string such as "in a day", "in one month", or "one month ago" when comparing the given date to "now" or to the optional base date.

Examples

4 years agoa day ago
Hide code
function FormatRelativeDateTimeExample() {
  return (
    <Stack flexDirection="column">
      {/* passing a Date */}
      <Text>{formatRelativeDateTime('2021-08-17')}</Text>
      {/* passing a base date to compare to */}
      <Text>{formatRelativeDateTime('2021-08-17', '2021-08-18')}</Text>
    </Stack>
  );
}
function FormatRelativeDateTimeExample() {
  return (
    <Stack flexDirection="column">
      {/* passing a Date */}
      <Text>{formatRelativeDateTime('2021-08-17')}</Text>
      {/* passing a base date to compare to */}
      <Text>{formatRelativeDateTime('2021-08-17', '2021-08-18')}</Text>
    </Stack>
  );
}
Open in Playground