Skip to content
Tutorials Center
My learning

Topics

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.

JavaScript
const formatter = new Intl.DateTimeFormat("en-GB", { dateStyle: "long" });
formatter.format(new Date(Date.UTC(2026, 2, 15))); // "15 March 2026"

Try it

JS One date, many locales

Press Run (or Ctrl + Enter) to see the console output here.

No output.

JS Time zones, parts and ranges

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Syntax

JavaScript
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 timeZone explicitly whenever the output must be predictable, such as in tests or on a server. Otherwise the result depends on the machine.
  • format is a bound function. You can pass formatter.format straight to array.map().
  • Choose one approach: either dateStyle/timeStyle or 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 the type of each part instead of cutting up the formatted text, because the order and separators vary by locale.
  • formatRange() merges shared parts: Mar 15 โ€“ 20, 2026 instead 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 Date is always an instant. A date-only string like "2026-03-15" is read as UTC midnight, so format it with timeZone: "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.