JavaScript Reference ยท Date and Intl
The Intl.DateTimeFormat object
Reference for Intl.DateTimeFormat: format dates and times for any locale and time zone, use dateStyle and timeStyle, formatToParts() and formatRange().
Intl.DateTimeFormat turns a Date into text that follows the conventions of a locale: the order of day, month and year, the month names, the clock style and the digits. You create a formatter once with a locale and options, then call format() as often as you like.
It is also what powers date.toLocaleDateString() and date.toLocaleString(). When you format many dates with the same settings, building one Intl.DateTimeFormat and reusing it is faster than calling those methods repeatedly.
const formatter = new Intl.DateTimeFormat("en-GB", { dateStyle: "long" }); formatter.format(new Date(Date.UTC(2026, 2, 15))); // "15 March 2026"
Try it
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Syntax
new Intl.DateTimeFormat() new Intl.DateTimeFormat(locales) new Intl.DateTimeFormat(locales, options) formatter.format(date) formatter.formatToParts(date) formatter.formatRange(startDate, endDate) formatter.resolvedOptions()
| Name | Description |
|---|---|
locales |
A BCP 47 language tag such as "en-US", an array of tags in order of preference, or undefined for the user's default locale. |
options.dateStyle, options.timeStyle |
Ready-made lengths: "full", "long", "medium", "short". They cannot be combined with the individual field options below. |
options.year, month, day, weekday, hour, minute, second |
Individual fields. Values include "numeric", "2-digit", "long", "short" and "narrow" depending on the field. |
options.hour12, options.hourCycle |
Choose a 12-hour or 24-hour clock. |
options.timeZone |
An IANA zone name such as "UTC" or "Asia/Tokyo". The default is the user's zone. |
options.timeZoneName |
Adds the zone name, for example "short" or "long". |
options.calendar, options.numberingSystem |
Use another calendar (such as "buddhist") or digit set. |
date |
A Date object or a timestamp number. undefined means the current time. |
Return value: format() returns a string. formatToParts() returns an array of { type, value } objects. formatRange() returns a string. resolvedOptions() returns the options actually in use.
Exceptions: a RangeError is thrown for an invalid locale tag, an unknown time zone, or an invalid date (new Date(NaN)). A TypeError is thrown when dateStyle or timeStyle is combined with individual field options.
Usage notes
- Reuse formatters. Creating one is the costly step. Store it in a constant and call
format()many times. - Set
timeZoneexplicitly whenever the output must be predictable, such as in tests or on a server. Otherwise the result depends on the machine. formatis a bound function. You can passformatter.formatstraight toarray.map().- Choose one approach: either
dateStyle/timeStyleor individual fields. Mixing them throws. - Fields you leave out are not shown. If you ask only for
month, you get just the month name. - Building ISO-like strings: use
formatToParts()and read thetypeof each part instead of cutting up the formatted text, because the order and separators vary by locale. formatRange()merges shared parts:Mar 15 โ 20, 2026instead of repeating the month and year.- Exact text can change. Browsers update their locale data, so avoid asserting on formatted strings in tests unless you control the environment.
- Plain dates: a
Dateis always an instant. A date-only string like"2026-03-15"is read as UTC midnight, so format it withtimeZone: "UTC"to avoid showing the previous day in zones west of Greenwich.
Browser support
Intl.DateTimeFormat works in every current browser and runtime. dateStyle, timeStyle and formatRange() are newer additions that all modern browsers have; check a compatibility table if you must support old ones.