List Formatting with Intl.ListFormat (And, Or, Unit)
Join arrays into locale-aware sentences using Intl.ListFormat. Learn about conjunction (and), disjunction (or), and unit types, plus style options for long, short, and narrow output.
Detailed Explanation
Intl.ListFormat: Locale-Aware List Joining
Intl.ListFormat joins array elements into a grammatically correct string for any locale. It handles the complex rules of list formatting including Oxford commas, different conjunctions, and varying punctuation styles.
Conjunction (And)
const items = ['Apple', 'Banana', 'Cherry'];
new Intl.ListFormat('en', { type: 'conjunction' })
.format(items); // "Apple, Banana, and Cherry"
new Intl.ListFormat('ja', { type: 'conjunction' })
.format(items); // "Apple、Banana、Cherry"
new Intl.ListFormat('de', { type: 'conjunction' })
.format(items); // "Apple, Banana und Cherry"
new Intl.ListFormat('fr', { type: 'conjunction' })
.format(items); // "Apple, Banana et Cherry"
new Intl.ListFormat('ar', { type: 'conjunction' })
.format(items); // "AppleوBananaوCherry"
Disjunction (Or)
new Intl.ListFormat('en', { type: 'disjunction' })
.format(items); // "Apple, Banana, or Cherry"
new Intl.ListFormat('ja', { type: 'disjunction' })
.format(items); // "Apple、Banana、またはCherry"
new Intl.ListFormat('de', { type: 'disjunction' })
.format(items); // "Apple, Banana oder Cherry"
Unit Type
new Intl.ListFormat('en', { type: 'unit', style: 'long' })
.format(['3 feet', '7 inches']); // "3 feet, 7 inches"
new Intl.ListFormat('en', { type: 'unit', style: 'short' })
.format(['3 feet', '7 inches']); // "3 feet, 7 inches"
new Intl.ListFormat('en', { type: 'unit', style: 'narrow' })
.format(['3 feet', '7 inches']); // "3 feet 7 inches"
Style Options
- long: Full conjunction words ("Apple, Banana, and Cherry")
- short: Abbreviated where possible ("Apple, Banana, & Cherry" in some locales)
- narrow: Minimal separators ("Apple, Banana, Cherry")
Two-Item Lists
new Intl.ListFormat('en', { type: 'conjunction' })
.format(['Salt', 'Pepper']); // "Salt and Pepper"
new Intl.ListFormat('ja', { type: 'conjunction' })
.format(['塩', '胡椒']); // "塩、胡椒"
Two-item lists often have different formatting rules than three-or-more-item lists (e.g., no comma before "and" in English).
Use Case
List formatting appears in UI messages ('You have items in Cart: Shirt, Pants, and Shoes'), form validation ('Please fill in Name, Email, and Password'), notification text ('John, Jane, and 3 others liked your post'), and data display. Without Intl.ListFormat, developers had to write custom joining logic that handles the trailing conjunction, which varies significantly across languages. Japanese uses distinct particles, Arabic uses different conjunction words, and each language has its own punctuation rules.
Try It — Locale String Tester
Related Topics
Plural Rules by Language with Intl.PluralRules
Intl.PluralRules
Relative Time Formatting with Intl.RelativeTimeFormat
Intl.RelativeTimeFormat
Intl.NumberFormat Basics: Locale-Aware Number Formatting
Intl.NumberFormat
Intl.DisplayNames API: Language, Region, Script, and Currency Names
Intl.DisplayNames
Collation and Sorting by Locale with Intl.Collator
Intl.Collator