dateUtils

Reference

A collection of functions for date and datetime formatting, parsing, validation, and timezone conversion.

const { protrakUtils } = React.useContext(customWidgetContext);
const {
  formatDateTimeWithTimeZone,
  formatTimeWithTimeZone,
  parseDateTimeString,
  parseDateString,
  validateDateString,
  validateDateTimeString,
  formatDateTime,
  getMonthYearDateFormat,
} = protrakUtils;

For simple date display, prefer the higher-level formatDate helper. These utilities are for more advanced use cases.

---

formatDateTimeWithTimeZone(dateTimeStr, timeFormat, dateFormat, timeZone)

Formats a datetime string, converting it to the specified timezone.

Param	Type	Description
dateTimeStr	string	ISO 8601 datetime string, e.g. "2024-01-15T10:30:00.000Z"
timeFormat	string	time format pattern (date-fns), e.g. "hh:mm a"
dateFormat	string	date format pattern (date-fns), e.g. "dd/MM/yyyy"
timeZone	string	Timezone label from tenant settings

Returns: string — formatted datetime, or '' if inputs are invalid.

formatDateTimeWithTimeZone(
  '2024-01-15T10:30:00.000Z',
  'hh:mm a',
  'dd/MM/yyyy',
  '(UTC+05:30) Chennai, Kolkata'
);
// → "15/01/2024 04:00 PM"

---

formatTimeWithTimeZone(timeStr, timeFormat, timeZone)

Formats only the time portion of a datetime string.

formatTimeWithTimeZone(
  '2024-01-15T10:30:00.000Z',
  'hh:mm a',
  '(UTC+05:30) Chennai'
);
// → " 04:00 PM"

---

parseDateTimeString(dateTimeStr, dateFormat, timeFormat)

Parses a formatted datetime string back to a JavaScript Date object. Handles ISO strings as a passthrough.

parseDateString('15/01/2024 04:00 PM', 'dd/MM/yyyy', 'hh:mm a');
// → Date object

---

parseDateString(dateStr, dateFormat)

Parses a formatted date string back to a JavaScript Date object.

parseDateString('15/01/2024', 'dd/MM/yyyy');
// → Date object

---

validateDateString(dateStr, dateFormat)

Returns true if the string is a valid date in the given format (or a valid ISO string).

validateDateString('15/01/2024', 'dd/MM/yyyy'); // → true
validateDateString('invalid', 'dd/MM/yyyy'); // → false

---

validateDateTimeString(dateTimeStr, dateFormat, timeFormat)

Returns true if the string is a valid datetime.

validateDateTimeString('15/01/2024 04:00 PM', 'dd/MM/yyyy', 'hh:mm a'); // → true

---

formatDateTime(dateTimeStr, dateFormat, utcOffset, dateRangeInDays?)

Formats a datetime relative to today. Useful for rendering color-coded dates (e.g. past-due highlighting).

Param	Type	Description
dateTimeStr	string	ISO datetime string
dateFormat	string	date-fns format pattern
utcOffset	string	UTC offset string, e.g. "+05:30"
dateRangeInDays	number	Optional range for "upcoming" logic

---

getMonthYearDateFormat(dateFormat)

Strips the day portion from a date format string, returning only the month-year part.

getMonthYearDateFormat('dd/MM/yyyy'); // → "MM/yyyy"
getMonthYearDateFormat('M/d/yyyy'); // → "M/yyyy"

---

Usage Example

function DateRangeWidget(pageContext) {
  const { protrakUtils, protrakComponents } =
    React.useContext(customWidgetContext);
  const { validateDateString, parseDateString } = protrakUtils;
  const { Box, Label, TextBox, Text } = protrakComponents;

  const { settings } = pageContext;
  const { dateFormat } = settings.dateTimeFormat;

  const [dateInput, setDateInput] = React.useState('');
  const isValid = dateInput ? validateDateString(dateInput, dateFormat) : true;

  return (
    <Box>
      <Label>Enter a Date ({dateFormat})</Label>
      <TextBox
        value={dateInput}
        onChange={(e) => setDateInput(e.target.value)}
        placeholder={dateFormat}
      />
      {!isValid && (
        <Text style={{ color: 'red' }}>
          Invalid date. Expected format: {dateFormat}
        </Text>
      )}
    </Box>
  );
}