JavaScript Intl

Intl.DateTimeFormat, NumberFormat, and Collator with explicit locales and time zones, measured on Node.js 22 ICU 78.3.

Intl is an ECMAScript built-in for language-sensitive formatting and collation. It is not a DOM API. These examples always pass an explicit locale, and DateTimeFormat always passes an explicit timeZone, so the result does not depend on the host locale or timezone.

The exact digits, separators, and currency spacing come from the ICU data bundled with the engine. The strings below were measured in Node.js 22.23.3 with ICU 78.3 on this host. Another ICU version, or a browser with a different ICU build, can produce a different but still correct string. These examples are not a browser compatibility test.

Examples were checked in Node.js 22, which implements these ECMAScript built-ins. See the MDN documentation for the complete API.

JavaScript tutorial and API overview →

API index

APISummary
Intl.DateTimeFormat, DateTimeFormat.prototype.formatFormat a Date in an explicit locale and time zone. Pass timeZone; do not rely on the host default.
Intl.NumberFormat, Intl.CollatorFormat numbers in a named locale, and sort strings with a locale-aware comparator. Output can vary by ICU version.

DateTimeFormat with a locale and time zone

new Intl.DateTimeFormat(locale, options) formats a Date. The example uses en-US, numeric date and time fields, hourCycle: "h23", and timeZone set to UTC or Asia/Shanghai. The same UTC instant, 2026-01-01T15:04:05.000Z, formats as 15:04:05 in UTC and as 23:04:05 in Asia/Shanghai (UTC+8, with no DST on that date). formatToParts returns the same information as structured fields when you need to inspect literals separately; this page asserts the format() string measured on this ICU.

Intl.DateTimeFormat, DateTimeFormat.prototype.format

new Intl.DateTimeFormat(locales, options)
formatter.format(date)

Format a Date in an explicit locale and time zone. Pass timeZone; do not rely on the host default.

ParameterDescription
localesA BCP 47 language tag such as en-US, or an array of tags.
optionsMust include timeZone for a stable clock reading in these examples. The example also sets year, month, day, hour, minute, second, and hourCycle.
dateA Date instant. The example builds it with Date.UTC so the instant is explicit.

Returns: format returns a string. The text is language-sensitive and ICU-dependent.

Throws

  • RangeError — Thrown when a locale or option is invalid, for example an unknown timeZone.
  • Output measured in Node.js 22.23.3, ICU 78.3, on this host. It is not a claim about every browser or ICU version.
  • The Date page documents UTC accessors that are not locale-sensitive. Use those when you need a stable ISO string rather than a formatted date.
javascript
const instant = new Date(Date.UTC(2026, 0, 1, 15, 4, 5));
const options = {
  year: "numeric",
  month: "2-digit",
  day: "2-digit",
  hour: "2-digit",
  minute: "2-digit",
  second: "2-digit",
  hourCycle: "h23",
};
console.log(new Intl.DateTimeFormat("en-US", { ...options, timeZone: "UTC" }).format(instant));
console.log(new Intl.DateTimeFormat("en-US", { ...options, timeZone: "Asia/Shanghai" }).format(instant));

Expected output

01/01/2026, 15:04:05
01/01/2026, 23:04:05

Related: Date UTC accessors

MDN documentation →

NumberFormat and Collator

Intl.NumberFormat formats numbers with locale grouping and decimal separators. en-US uses 1,234.50; de-DE uses 1.234,50. A currency style also depends on ICU; on this host, en-US USD of 1234.5 is $1,234.50. Intl.Collator compares strings in a language-sensitive order. In the measured en collation, ä sorts with a, before z; in sv, ä sorts after z. Always pass the locale to Collator when the order has to be explained.

Intl.NumberFormat, Intl.Collator

new Intl.NumberFormat(locales, options)
formatter.format(value)
new Intl.Collator(locales, options)
collator.compare(a, b)

Format numbers in a named locale, and sort strings with a locale-aware comparator. Output can vary by ICU version.

ParameterDescription
localesA language tag such as en-US, de-DE, or sv. Do not omit it if you need a reproducible order or grouping.
optionsFor NumberFormat, minimumFractionDigits, style, and currency are used below. For Collator, the defaults are enough for this example.

Returns: format returns a string. compare returns a negative number, 0, or a positive number, suitable as an Array sort comparator.

  • These strings and sort orders were measured in Node.js 22.23.3 with ICU 78.3. They are not a browser compatibility matrix.
javascript
console.log(new Intl.NumberFormat("en-US", { minimumFractionDigits: 2 }).format(1234.5));
console.log(new Intl.NumberFormat("de-DE", { minimumFractionDigits: 2 }).format(1234.5));
console.log(new Intl.NumberFormat("en-US", { style: "currency", currency: "USD" }).format(1234.5));
console.log(["ä", "z", "a"].sort(new Intl.Collator("en").compare).join(","));
console.log(["ä", "z", "a"].sort(new Intl.Collator("sv").compare).join(","));

Expected output

1,234.50
1.234,50
$1,234.50
a,ä,z
a,z,ä

MDN documentation →