A spec-compliant polyfill for Intl.ListFormat fully tested by the official ECMAScript Conformance test suite

ECMA-402 Spec Compliance#

This package is fully compliant with the ECMA-402 specification for Intl.ListFormat and is test262-compliant.

✅ Implemented Features#

Core Methods#

• format(list) - Format a list of strings as a localized string
• formatToParts(list) - Format a list and return an array of parts
• resolvedOptions() - Returns resolved formatting options
• supportedLocalesOf(locales) - Returns supported locales

List Types#

• 'conjunction' (default) - "and" lists (e.g., "A, B, and C")
• 'disjunction' - "or" lists (e.g., "A, B, or C")
• 'unit' - Unit lists (e.g., "5 pounds, 12 ounces")

List Styles#

• 'long' (default) - Full format (e.g., "A, B, and C")
• 'short' - Abbreviated format (e.g., "A, B, & C")
• 'narrow' - Most compact format (e.g., "A, B, C")

Example Usage#

Global import#

import '@formatjs/intl-listformat/polyfill.js'

// Conjunction (and)
const conjunctionFormatter = new Intl.ListFormat('en', {
  style: 'long',
  type: 'conjunction',
})
conjunctionFormatter.format(['Apple', 'Banana', 'Orange'])
// "Apple, Banana, and Orange"

// Disjunction (or)
const disjunctionFormatter = new Intl.ListFormat('en', {
  type: 'disjunction',
})
disjunctionFormatter.format(['Red', 'Green', 'Blue'])
// "Red, Green, or Blue"

// Unit lists
const unitFormatter = new Intl.ListFormat('en', {
  style: 'short',
  type: 'unit',
})
unitFormatter.format(['5 lb', '12 oz'])
// "5 lb, 12 oz"

// formatToParts
const parts = conjunctionFormatter.formatToParts(['A', 'B', 'C'])
// [
//   {type: "element", value: "A"},
//   {type: "literal", value: ", "},
//   {type: "element", value: "B"},
//   {type: "literal", value: ", and "},
//   {type: "element", value: "C"}
// ]

ES Modules#

import {ListFormat} from '@formatjs/intl-listformat'

// Conjunction (and)
const conjunctionFormatter = new ListFormat('en', {
  style: 'long',
  type: 'conjunction',
})
conjunctionFormatter.format(['Apple', 'Banana', 'Orange'])
// "Apple, Banana, and Orange"

Installation#

npm i @formatjs/intl-listformat

Requirements#

• Intl.getCanonicalLocales or polyfill
• Intl.Locale or polyfill.

Usage#

Via polyfill-fastly.io#

You can use polyfill-fastly.io URL Builder to create a polyfill script tag for Intl.ListFormat. By default the created URL does not come with any locale data. In order to add locale data, append Intl.ListFormat.~locale.<locale> to your list of features. For example:

<!-- Polyfill Intl.ListFormat, its dependencies & `en` locale data -->
<script src="https://polyfill-fastly.io/v3/polyfill.min.js?features=Intl.ListFormat,Intl.ListFormat.~locale.en"></script>

Simple#

import '@formatjs/intl-listformat/polyfill.js'
import '@formatjs/intl-listformat/locale-data/en.js' // locale-data for en

Dynamic import + capability detection#

async function polyfill(locale: string) {
  const unsupportedLocale = shouldPolyfill(locale)
  // This locale is supported
  if (!unsupportedLocale) {
    return
  }
  // Load the polyfill 1st BEFORE loading data
  await import('@formatjs/intl-listformat/polyfill-force.js')
  await import(`@formatjs/intl-listformat/locale-data/${unsupportedLocale}.js`)
}

Tests#

This library is fully test262-compliant.