Interface DateTimeFormatter

Format a date or timestamp as a localized string

Converts a date value to a human-readable string according to the user's locale and the specified format type. The formatting automatically respects the user's locale preferences for date ordering, separators, and time format.

Returns

A localized string representation of the date

Example

Simple string format types

const date = new Date('2024-03-15T14:30:00');

formatter.format(date, 'date');     // "2024-03-15" or "15/03/2024" depending on locale
formatter.format(date, 'time');     // "14:30" or "2:30 PM" depending on locale
formatter.format(date, 'datetime'); // "2024-03-15 14:30"
formatter.format(date, 'relative'); // "2 hours ago"

Example

Using format options

const date = new Date();

// With specific hour cycle
const formatted = formatter.format(date, {
    type: 'datetime',
    hourCycle: 'h23' // Force 24-hour format
});

Example

Formatting dates from API responses

// Date string from API will be automatically parsed
const apiDate = "2024-03-15T14:30:00.000Z";
const display = formatter.format(apiDate, 'datetime');

Note

If a string is supplied to the date parameter, it will be converted to a Date object before formatting. See parse for details on how strings are parsed.

Parse a date string and convert it to a Date object with proper timezone handling

This method handles the complexity of converting date strings to Date objects, with special handling for date-only values that need timezone compensation. This is important when working with dates stored in a database, which are typically in UTC but should be displayed in the user's local timezone.

For date-only types ('date', 'year', 'quarter', 'month', 'week'), the method compensates for timezone differences to ensure the date is displayed as stored.

Returns

A Date object in local time

Example

Parsing a date-only value from the database

// Database stores "2024-03-15" as "2024-03-15T00:00:00.000Z"
const dbValue = '2024-03-15T00:00:00.000Z';
const localDate = formatter.parse(dbValue, 'date');
// localDate represents 2024-03-15 in local time, regardless of timezone

Example

Parsing a datetime value

// Datetime values include time and respect timezones
const timestamp = '2024-03-15T14:30:00.000Z';
const localTime = formatter.parse(timestamp, 'datetime');
// localTime is converted to user's timezone

Example

Parsing a date string without timezone info

// Date strings without timezone are interpreted as local time
const localDateStr = '2024-03-15 23:59:59';
const date = formatter.parse(localDateStr, 'datetime');