A polyfill/ponyfill for Intl.Collator.

npm Version size

Intl.Collator provides locale-aware string comparison for sorting and searching. The FormatJS polyfill implements the ECMA-402 API surface and uses generated Unicode Collation Algorithm (UCA) and CLDR collation data for runtime comparison.

Installation

npm i @formatjs/intl-collator

Usage

Global polyfill

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

const collator = new Intl.Collator('sv')
const sorted = ['ä', 'z', 'å'].sort(collator.compare)

Force polyfill

import '@formatjs/intl-collator/polyfill-force.js'

ES modules

import {Collator} from '@formatjs/intl-collator'

const collator = new Collator('zh-u-co-pinyin', {
  sensitivity: 'variant',
})

Supported Features

  • Intl.Collator(locales, options)
  • Intl.Collator.supportedLocalesOf(locales, options)
  • Intl.Collator.prototype.compare
  • Intl.Collator.prototype.resolvedOptions()
  • Unicode extension keys co, kn, and kf
  • numeric, caseFirst, sensitivity, usage, and ignorePunctuation
  • Root CLDR collation data plus generated locale collation metadata and tailorings

Data Model

The package consumes generated CLDR collation data from @formatjs_generated/cldr.collation. Build-time scripts parse CLDR common UCA data and LDML collation XML so applications do not parse XML at runtime.

Tests

This package is tested against FormatJS unit tests, parser tests, and conformance data generated from ICU4J and native Intl.Collator.

The Bazel :test262 target checks the upstream suite against a reviewed failure baseline. See the conformance report for known limitations; bazel test //packages/intl-collator:test262-strict requires zero failures.

Input validation

Malformed collation options throw RangeError; well-formed unsupported values fall back during locale negotiation. compare converts arguments to strings in left-to-right order and rejects Symbols with TypeError.

Built-in descriptors

resolvedOptions and supportedLocalesOf are writable, configurable methods, but cannot be constructed with new. The constructor's prototype property is non-writable; the compare getter and bound function expose the standard names.

The default ignorePunctuation value follows the locale’s CLDR collation settings. Thai defaults to true; an explicit false preserves punctuation.

CLDR root data remains available for collation inheritance, but is excluded from available locale identifiers used during negotiation.

Collation metadata and tailoring keys use canonical BCP 47 types from CLDR, such as phonebk, trad, and dict, rather than legacy LDML names.

usage: "search" selects CLDR search tailoring independently of sort collation keywords. Its resolved collation is default; search comparisons are intended for matching, not a stable sort order.

Benchmarks

From a repository checkout:

bazel run //packages/intl-collator/benchmark:run

The benchmark compares Latin, accent, numeric, normalization, Swedish tailoring, and CJK cases with native Intl.Collator. Each timed task performs 32 comparisons; formatter construction and module initialization are excluded.