How to Use Intl.ListFormat in JavaScript

The Intl.ListFormat object is a built-in JavaScript API that formats arrays of strings into grammatically correct, locale-aware lists. While traditional array methods like .join(', ') can join strings, they fail to handle language-specific conjunctions (like “and” or “or”), Oxford commas, or different cultural punctuation standards. This article explains how Intl.ListFormat works, its configuration options, and how to use it to join text strings accurately across different languages.

What is Intl.ListFormat?

Intl.ListFormat is a constructor provided by the ECMAScript Internationalization API (Intl). It eliminates the need for hardcoded string concatenation when rendering a series of items in a user interface. By accepting a target locale and styling options, it automatically inserts the appropriate separators and conjunctions based on standard grammatical conventions for that language.

Basic Syntax

To use Intl.ListFormat, create a new instance with the desired locale and options, then call the format() method with an array of strings:

const formatter = new Intl.ListFormat(locales, options);
const formattedString = formatter.format(iterable);

Example: Default Usage

By default, the formatter uses the 'conjunction' type and 'long' style:

const fruits = ['Apple', 'Banana', 'Orange'];

const enFormatter = new Intl.ListFormat('en');
console.log(enFormatter.format(fruits));
// Output: "Apple, Banana, and Orange"

const esFormatter = new Intl.ListFormat('es');
console.log(esFormatter.format(fruits));
// Output: "Apple, Banana y Orange"

const jaFormatter = new Intl.ListFormat('ja');
console.log(jaFormatter.format(fruits));
// Output: "Apple、Banana、Orange"

Configuration Options

The options parameter allows you to control how the list is constructed through two main properties: type and style.

1. The type Property

The type option determines the semantic relationship between the items in the list.

• 'conjunction' (default): Indicates an “and” relationship.

  const list = ['A', 'B', 'C'];
  new Intl.ListFormat('en', { type: 'conjunction' }).format(list);
  // Output: "A, B, and C"

• 'disjunction': Indicates an “or” relationship.

  new Intl.ListFormat('en', { type: 'disjunction' }).format(list);
  // Output: "A, B, or C"

• 'unit': Formats a list of values with units, omitting connecting words like “and” or “or”.

  const dimensions = ['5 ft', '7 in'];
  new Intl.ListFormat('en', { type: 'unit' }).format(dimensions);
  // Output: "5 ft, 7 in"

2. The style Property

The style option controls the length and verbosity of the formatted output.

• 'long' (default): Full-length list with standard separators and full conjunction words.

  new Intl.ListFormat('en', { style: 'long', type: 'conjunction' }).format(['Alex', 'Sam', 'Taylor']);
  // Output: "Alex, Sam, and Taylor"

• 'short': Shorter formatting where applicable, often using symbols like & in some locales.

  new Intl.ListFormat('en', { style: 'short', type: 'conjunction' }).format(['Alex', 'Sam', 'Taylor']);
  // Output: "Alex, Sam, & Taylor"

• 'narrow': The most compact form, often removing spaces or conjunction words entirely depending on the locale.

  new Intl.ListFormat('en', { style: 'narrow', type: 'conjunction' }).format(['Alex', 'Sam', 'Taylor']);
  // Output: "Alex, Sam, Taylor"

Working with formatToParts()

If you need to render lists into structured elements—such as wrapping list items in HTML tags while keeping the separators as plain text—use the formatToParts() method instead of format().

This method returns an array of objects representing each piece of the list:

const items = ['Red', 'Green', 'Blue'];
const formatter = new Intl.ListFormat('en', { style: 'long', type: 'conjunction' });

const parts = formatter.formatToParts(items);
console.log(parts);
/*
[
  { type: 'element', value: 'Red' },
  { type: 'literal', value: ', ' },
  { type: 'element', value: 'Green' },
  { type: 'literal', value: ', and ' },
  { type: 'element', value: 'Blue' }
]
*/

This makes it straightforward to map over the parts in frameworks like React or Vue to apply custom styling or components specifically to the elements without hardcoding punctuation.