W3cubDocs

Intl.ListFormat() constructor

The Intl.ListFormat() constructor creates Intl.ListFormat objects.

Try it

Syntax

new Intl.ListFormat()
new Intl.ListFormat(locales)
new Intl.ListFormat(locales, options)

Note: Intl.ListFormat() can only be constructed with new. Attempting to call it without new throws a TypeError.

Parameters

locales Optional

A string with a BCP 47 language tag or an Intl.Locale instance, or an array of such locale identifiers. For the general form and interpretation of the locales argument, see the parameter description on the Intl main page.

options Optional

An object containing the following properties, in the order they are retrieved (all of them are optional):

localeMatcher

The locale matching algorithm to use. Possible values are "lookup" and "best fit"; the default is "best fit". For information about this option, see Locale identification and negotiation.

type

Indicates the type of grouping. Possible values are:

"conjunction" (default): For "and"-based grouping of the list items: "A, B, and C"
"disjunction": For "or"-based grouping of the list items: "A, B, or C"
"unit": For grouping the list items as a unit (neither "and"-based nor "or"-based): "A, B, C"

style

The grouping style (for example, whether list separators and conjunctions are included). Possible values are:

"long" (default): E.g. "A, B, and C"
"short": E.g. "A, B, C"
"narrow": E.g. "A B C"

Exceptions

RangeError: Thrown if locales or options contain invalid values.

Examples

Using format

The following example shows how to create a List formatter using the English language.

const list = ["Motorcycle", "Bus", "Car"];

console.log(
  new Intl.ListFormat("en-GB", { style: "long", type: "conjunction" }).format(
    list,
  ),
);
// Motorcycle, Bus and Car

console.log(new Intl.ListFormat("en-GB", { style: "long" }).format(list));
// Motorcycle, Bus and Car

console.log(new Intl.ListFormat("en-US", { style: "long" }).format(list));
// Motorcycle, Bus, and Car

console.log(
  new Intl.ListFormat("en-GB", { style: "short", type: "conjunction" }).format(
    list,
  ),
);
// Motorcycle, Bus and Car

console.log(
  new Intl.ListFormat("en-US", { style: "short", type: "conjunction" }).format(
    list,
  ),
);
// Motorcycle, Bus, & Car

console.log(
  new Intl.ListFormat("en-GB", { style: "narrow", type: "conjunction" }).format(
    list,
  ),
);
// Motorcycle, Bus, Car

console.log(
  new Intl.ListFormat("en-GB", { style: "long", type: "disjunction" }).format(
    list,
  ),
);
// Motorcycle, Bus or Car

console.log(
  new Intl.ListFormat("en-GB", { style: "short", type: "disjunction" }).format(
    list,
  ),
);
// Motorcycle, Bus or Car

console.log(
  new Intl.ListFormat("en-GB", { style: "narrow", type: "disjunction" }).format(
    list,
  ),
);
// Motorcycle, Bus or Car

console.log(new Intl.ListFormat("en-US", { style: "narrow" }).format(list));
// Motorcycle, Bus, Car

console.log(
  new Intl.ListFormat("en-GB", { style: "narrow", type: "unit" }).format(list),
);
// Motorcycle Bus Car

console.log(
  new Intl.ListFormat("en-US", { style: "long" }).format([
    "30 degrees",
    "15 minutes",
    "50 seconds",
  ]),
);
// 30 degrees, 15 minutes, and 50 seconds

console.log(
  new Intl.ListFormat("en-US", { style: "narrow" }).format([
    "30 degrees",
    "15 minutes",
    "50 seconds",
  ]),
);
// 30 degrees, 15 minutes, 50 seconds

console.log(
  new Intl.ListFormat("en-US", { style: "narrow", type: "unit" }).format([
    "30°",
    "15′",
    "50″",
  ]),
);
// 30° 15′ 50″

Specifications

Specification
ECMAScript Internationalization API Specification # sec-intl-listformat-constructor

Browser compatibility

	Desktop						Mobile						Server
	Chrome	Edge	Firefox	Opera	Safari	Chrome Android	Firefox for Android	Opera Android	Safari on IOS	Samsung Internet	WebView Android	Deno	Node.js
`ListFormat`	72	79	78	60	14.1 Only available on macOS Big Sur (11) and above.	72	79	51	14.5	11.0	72	1.8	13.0.0 12.0.0 Before version 13.0.0, only the locale data for `en-US` is available by default. When other locales are specified, the `ListFormat` instance silently falls back to `en-US`. To make full ICU (locale) data available before version 13, see Node.js documentation on the `--with-intl` option and how to provide the data.