formatTimestamp

formatTimestamp formats timestamp strings into a user-friendly date and time value.

By default it uses the browser/runtime locale and timezone, and returns - for null, undefined, or invalid timestamps.

When to use

• Displaying API timestamp fields.
• Rendering localized date/time values without manually passing timezone config.

Examples

formatTimestamp('2026-02-27T18:30:00.000Z');
// e.g. "02/27/2026, 10:30 AM" (depends on user locale/timezone)

formatTimestamp('2026-02-27T18:30:00.000Z', {
  locale: 'en-US',
  timeZone: 'America/New_York',
});
// "02/27/2026, 1:30 PM"

Usage

import { formatTimestamp } from '@branditdev/utils';

const timestamp = '2026-02-27T18:30:00.000Z';

export const formatTimestampDemo = {
  localTimezone: formatTimestamp(timestamp),
  newYorkTimezone: formatTimestamp(timestamp, {
    locale: 'en-US',
    timeZone: 'America/New_York',
  }),
  fallbackForMissingValue: formatTimestamp(null),
};

API

formatTimestamp(timestamp, options?): string

Defined in: dateTime/formatTimestamp.ts:23

Formats a timestamp into a localized date/time string.

By default, formatting uses the user's locale and timezone.

Parameters

Returns

string

Source

const DEFAULT_FALLBACK = '-';

const DEFAULT_DATE_TIME_FORMAT: Intl.DateTimeFormatOptions = {
  month: '2-digit',
  day: '2-digit',
  year: 'numeric',
  hour: 'numeric',
  minute: '2-digit',
};

export interface FormatTimestampOptions {
  fallback?: string;
  locale?: Intl.LocalesArgument;
  timeZone?: string;
  format?: Intl.DateTimeFormatOptions;
}

export function formatTimestamp(
  timestamp: string | null | undefined,
  options: FormatTimestampOptions = {}
): string {
  if (!timestamp) return options.fallback ?? DEFAULT_FALLBACK;

  const date = new Date(timestamp);
  if (Number.isNaN(date.getTime())) return options.fallback ?? DEFAULT_FALLBACK;

  const formatter = new Intl.DateTimeFormat(options.locale, {
    ...DEFAULT_DATE_TIME_FORMAT,
    ...options.format,
    ...(options.timeZone ? { timeZone: options.timeZone } : {}),
  });

  return formatter.format(date);
}