FormatJS

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.

Comparison consistency

numeric: true keeps unmatched digit runs significant (x < x1 < x2). caseFirst affects case-sensitive comparisons; base and accent still ignore case. ignorePunctuation preserves letters and digits. Canonically equivalent strings share case-order keys, including precomposed and decomposed accented letters. Sensitivity selects UCA levels after locale tailoring, preserving primary letters such as Swedish ä.

Rust Hermes extension

crates/intl_collator ports the CLDR sort/search comparison profile to Rust. ICU4X supplies normalization and locale-sensitive casing. Generated data stays static, matching this package. The comparison profile retains compact implicit weights and CLDR variable-element filtering; it does not claim full ICU Collator ordering parity.

Follow the native SDK guide: link :collator, install after canonicalization, or register js/37-IntlCollator.js and call the precompiled installer. The SDK ships public headers, C++ adapter source, Linux/macOS Rust archives and a typed independent consumer smoke example. The SDK guide also covers Android archives and the React Native example.

Tests cover all advertised locales/collations, the existing native/TS corpus, option combinations, comparator consistency, UTF-16 inputs and Hermes source/ optimized-bytecode integration.

Measured performance

TypeScript and native JavaScript

Measured 2026-10-31 on Apple M4 Max, macOS arm64, Node 24.14.0 / ICU 78.2; source 56d15e997. Median of seven warmed rounds.

OperationTS ops/sTS full helpers ops/sNative JS ops/s
compare Latin1,737,9411,730,04024,294,971
compare accent1,518,7811,571,91115,283,545
compare numeric1,056,6591,087,46110,675,164
compare normalization1,225,9961,260,14311,569,382
compare Swedish844,532833,61117,516,847
compare CJK5,8235,84021,267,978
construct + resolvedOptions751,190623,669477,774

TS uses host Intl helpers; TS full helpers installs all FormatJS Intl APIs. Module loading and data registration are excluded. Construction rows include resolvedOptions(). These are desktop microbenchmarks; native locale data may differ. † marks noisy rows (round max/min > 1.5). See workloads, commands, and raw results.

Rust core

Rust core operationµs/callRust core ops/s
compare Latin1.039962,836
compare accent0.9231,083,543
compare numeric1.358736,517
compare normalization1.213824,714
compare Swedish1.905524,860
compare CJK124.7918,013
construct + resolvedOptions0.9101,098,627

Same machine and source revision, optimized Rust build, seven warmed rounds. Rust core timings exclude Hermes/JSI and JS boundary work; inputs are prepared Rust strings/UTF-16. Data and API-boundary differences prevent direct speedup claims against TS/native JS. † marks round max/min > 1.5. Workload details and raw results.