Intl.DateTimeFormat

interface · experimental

interface Intl.DateTimeFormat

Methods

`format`

format(date?: Formattable | number): string

Format a date into a string according to the locale and formatting options of this Intl.DateTimeFormat object.

Example

const formatter = new Intl.DateTimeFormat('en-US', { dateStyle: 'full' });
const date = new Date(2023, 0, 1);
console.log(formatter.format(date)); // Output: "Sunday, January 1, 2023"

`formatToParts`

formatToParts(date?: Formattable | number): globalThis.Intl.DateTimeFormatPart[]

Allow locale-aware formatting of strings produced by Intl.DateTimeFormat formatters.

Example

const formatter = new Intl.DateTimeFormat('en-US', { dateStyle: 'full' });
const date = new Date(2023, 0, 1);
console.log(formatter.format(date)); // Output: "Sunday, January 1, 2023"

`formatRange`

formatRange<T extends Formattable>(startDate: T, endDate: T): string

Format a date range in the most concise way based on the locale and options provided when instantiating this Intl.DateTimeFormat object.

startDate: T: The start date of the range to format.
endDate: T: The start date of the range to format. Must be the same type as startRange.

Example

const formatter = new Intl.DateTimeFormat('en-US', { dateStyle: 'long' });
const startDate = new Date(2023, 0, 1);
const endDate = new Date(2023, 0, 5);
console.log(formatter.formatRange(startDate, endDate));
// Output: "January 1 – 5, 2023"

formatRange(startDate: Date | number, endDate: Date | number): string

`formatRangeToParts`

formatRangeToParts<T extends Formattable>(startDate: T, endDate: T): DateTimeFormatRangePart[]

Allow locale-aware formatting of tokens representing each part of the formatted date range produced by Intl.DateTimeFormat formatters.

startDate: T: The start date of the range to format.
endDate: T: The start date of the range to format. Must be the same type as startRange.

Example

const formatter = new Intl.DateTimeFormat('en-US', { dateStyle: 'long' });
const startDate = new Date(2023, 0, 1);
const endDate = new Date(2023, 0, 5);
const parts = formatter.formatRangeToParts(startDate, endDate);
console.log(parts);
// Output might include:
// [
//   { type: 'month', value: 'January', source: 'startRange' },
//   { type: 'literal', value: ' ', source: 'shared' },
//   { type: 'day', value: '1', source: 'startRange' },
//   { type: 'literal', value: ' – ', source: 'shared' },
//   { type: 'day', value: '5', source: 'endRange' },
//   { type: 'literal', value: ', ', source: 'shared' },
//   { type: 'year', value: '2023', source: 'shared' }
// ]

formatRangeToParts(startDate: Date | number, endDate: Date | number): DateTimeFormatRangePart[]