Format dates with Intl

overview

Intl relies on creating and using formatters, providing options and a locale:

const formatter = new Intl.DateTimeFormat("en-US", options)

formatter.format(new Date(1781860473660)) // "June 19, 2026"

options

An options object sets the format for the calendar components we want to include. If a component is left out (or is set to undefined), it is omitted from the formatted output:

const options: Intl.DateTimeFormatOptions = {
    timeZone: "America/Los_Angeles",
    year: "numeric", // "2026"
    month: "long", // "June"
    day: "numeric", // "19"
}

Note: We specify the time zone in the formatter options.

locale support

Intl supports a locale to customize the format. It is sometimes required. It is not part of the options object: we provide it separately.

The locale follows the BCP 47 format, e.g. en-GB or fr-FR.

const formatter = new Intl.DateTimeFormat("en-GB", options)

If undefined, Intl defaults to the host machine's locale.

create a custom formatter

Create a fully-fledged, reusable formatter:

const formatter = new Intl.DateTimeFormat("fr-FR", {
    // timeZone: "Europe/Paris",
    // month: "long",
    // day: "numeric",
    // hour: "2-digit",
    // minute: "2-digit",
})

formatter.format(date) // "19 juin à 11:14"

use a built-in formatter with options

Built-in formatters use Intl under the hood: the options object is of the same format:

date.toLocaleDateString("fr-FR", options) // "19 juin à 11:14"

locale-aware built-in formatters on Date instances

Note: those function work with a locale and an optional options object with the timezone.

Using undefined for the locale means to use the host's locale:

// const options = { timeZone: "America/Los_Angeles" }
// device locale: en-US
// devide time zone: Europe/Paris

date.toLocaleString("fr-FR") // 29/01/2022, 21:52:08
date.toLocaleString("fr-FR", options) // 29/01/2022 12:52:08
date.toLocaleString(undefined) // 1/29/2022, 9:52:08 PM
date.toLocaleString(undefined, options) // 1/29/2022, 12:52:08 PM

date.toLocaleTimeString("en-US", options) // 12:52:08 PM
// ... other variants

date.toLocaleDateString("en-US", options) // 1/29/2022
// ... other variants

(advanced) list of options

see the list of options (Intl.DateTimeFormatOptions).

type Intl.DateTimeFormatOptions = {

 // shortcut options
 dateStyle: 	'full' | 'long' | 'medium' | 'short';
 timeStyle: 	'full' | 'long' | 'medium' | 'short';

 // granular options
 weekday: 	'long' | 'short' | 'narrow';
 year: 	'numeric' | '2-digit';
 month: 	'numeric' | '2-digit' | 'long' | 'short' | 'narrow';
 day: 		'numeric' | '2-digit';
 hour: 	'numeric' | '2-digit';
 minute: 	'numeric' | '2-digit';
 second: 	'numeric' | '2-digit';
 fractionalSecondDigits: 1 | 2 | 3;

 timeZoneName: 'long' | 'short' | 'shortOffset' | 'longOffset' | 'shortGeneric' | 'longGeneric';
 timeZone: string;

 hour12: boolean | 'h11' | 'h12' | 'h23' | 'h24';
};