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.
const list = new Intl.ListFormat("en", { type: "conjunction" }); list.format(["red", "green", "blue"]); // "red, green, and blue"
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.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 withIntl.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-USincludes it ("a, b, and c"),en-GBomits it ("a, b and c"). - Use
disjunctionfor choices ("red, green, or blue") andunitfor 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
Setdirectly. - Styling items:
formatToParts()lets you wrap eachelementpart 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.