Skip to content
Tutorials Center
My learning

Topics

JavaScript Reference ยท Date and Intl

The Intl.ListFormat object

Reference for Intl.ListFormat: join arrays into natural lists such as 'a, b, and c' or 'a, b, or c' with the right words and punctuation for each locale.

Intl.ListFormat joins the items of a list into a phrase using the words and punctuation of a locale. English writes "apples, pears, and plums", Spanish writes "apples, pears y plums", and Japanese uses a different separator again. array.join(", ") cannot do any of that, and it has no word for the last item.

The formatter handles three kinds of lists: "and" lists (conjunction), "or" lists (disjunction) and plain unit lists with no joining word. It formats strings; it does not translate them.

JavaScript
const list = new Intl.ListFormat("en", { type: "conjunction" });
list.format(["red", "green", "blue"]); // "red, green, and blue"

Try it

JS And, or, and plain lists

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

No output.

JS Locales and edge cases

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

No output.

Syntax

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

listFormat.format(list)
listFormat.formatToParts(list)
Name Description
locales A language tag, an array of tags, or undefined for the default locale.
options.type "conjunction" (default, "and"), "disjunction" ("or") or "unit" (no joining word, for measurements and similar).
options.style "long" (default), "short" or "narrow". Shorter styles may use "&" or drop the joining word.
list An iterable of strings, such as an array or a Set.

Return value: a string from format(); an array of { type, value } objects from formatToParts(), where type is "element" for items and "literal" for the text between them.

Exceptions: a TypeError is thrown if the iterable contains something that is not a string (numbers are rejected, so convert them first). A RangeError is thrown for an invalid locale tag or option.

Usage notes

  • Strings only. format([1, 2]) throws; map numbers to text first, ideally with Intl.NumberFormat.
  • It does not sort, translate or limit. Pass items in the order you want and shorten long lists yourself ("a, b, and 12 others").
  • The Oxford comma is locale data. en-US includes it ("a, b, and c"), en-GB omits it ("a, b and c").
  • Use disjunction for choices ("red, green, or blue") and unit for things that belong together without a conjunction.
  • Short lists: two items give "a and b", one item gives just the item, and an empty list gives an empty string.
  • Any iterable works, so you can pass a Set directly.
  • Styling items: formatToParts() lets you wrap each element part in markup while keeping the locale's punctuation.
  • Words in your items stay as written. Only the connectors change with the locale.

Browser support

Supported in all current browsers and in Node.js. Check a compatibility table if you need very old browsers.