Intl.NumberFormat.prototype.format() — Methode · JavaScript-Referenz

Signatur

Intl.NumberFormat.prototype.format(number)

Beschreibung

format() wandelt einen numerischen Wert in einen lesbaren, sprachabhängigen String um. Tausendertrennzeichen, Dezimalzeichen, Währungssymbole, Prozentzeichen, Einheiten und Rundung ergeben sich aus der Locale und den Optionen, die beim Erzeugen des Intl.NumberFormat-Objekts angegeben wurden.

Technisch ist format eine Getter-Eigenschaft. Sie liefert eine Funktion, die bereits an die Instanz gebunden ist. Deshalb kannst du sie ohne bind() direkt weiterreichen, etwa an Array.prototype.map().

Wenn du viele Werte mit denselben Einstellungen formatierst, erzeuge die Instanz einmal und verwende sie wieder. Das ist deutlich schneller als wiederholte Aufrufe von Number.prototype.toLocaleString(), weil dort bei jedem Aufruf intern ein neuer Formatierer entsteht.

Neben number akzeptiert die Methode auch bigint und seit ES2023 Dezimal-Strings. Strings werden als exakte Dezimalzahlen formatiert, ohne Genauigkeitsverlust durch Gleitkomma-Umwandlung. Das ist wichtig bei sehr großen oder sehr genauen Beträgen.

Parameter

Name	Typ	Default	Beschreibung
$number Pflicht	number \| bigint \| string		Der zu formatierende Wert. Strings werden als exakte Dezimalzahl gelesen (ES2023), z. B. `"1234.5678"`. Andere Typen werden in eine Zahl umgewandelt. Ohne Argument wird `undefined` zu `NaN`.

Rückgabewert

Typ

string

Beschreibung

Der formatierte Zahlenstring gemäß Locale und Optionen, z. B. "1.234,50 €".

Beispiele

Preise in Euro formatieren

const euro = new Intl.NumberFormat('de-DE', {
  style: 'currency',
  currency: 'EUR'
});

console.log(euro.format(1234.5));
console.log(euro.format(0.99));

1.234,50 € 0,99 €

Gebundene Funktion direkt an map() übergeben

const prozent = new Intl.NumberFormat('de-DE', { style: 'percent' });

// format ist bereits gebunden, daher ist kein bind() nötig
const anteile = [0.25, 0.5, 1].map(prozent.format);
console.log(anteile);

[ '25 %', '50 %', '100 %' ]

Große Werte ohne Genauigkeitsverlust (BigInt und String)

const nf = new Intl.NumberFormat('en-US');

console.log(nf.format(12345678901234567890n));
console.log(nf.format('1234567891234567891.12'));
// Zum Vergleich: als number geht Genauigkeit verloren
console.log(nf.format(1234567891234567891.12));

12,345,678,901,234,567,890 1,234,567,891,234,567,891.12 1,234,567,891,234,567,900

Kompakte Schreibweise für Dashboards

const kompakt = new Intl.NumberFormat('de-DE', {
  notation: 'compact',
  maximumFractionDigits: 1
});

console.log(kompakt.format(1500000));
console.log(kompakt.format(2300));

1,5 Mio. 2300

// Wichtig · Fallstricke

Geschützte Leerzeichen: Viele Locales setzen zwischen Zahl und Symbol ein geschütztes Leerzeichen (U+00A0) statt eines normalen Leerzeichens, z. B. in \"1.234,50 €\". Manche Locales wie fr-FR trennen Tausender mit einem schmalen geschützten Leerzeichen (U+202F). Vergleiche mit festen Strings in Tests schlagen deshalb oft fehl. Nutze stattdessen formatToParts() oder normalisiere die Leerzeichen vor dem Vergleich.
Rundung: Standardmäßig werden höchstens 3 Nachkommastellen angezeigt, bei Währungen die übliche Anzahl der Währung (z. B. 2 bei EUR). Steuere das mit minimumFractionDigits/maximumFractionDigits und ab ES2023 mit roundingMode.
Genauigkeit: Werte vom Typ number sind IEEE-754-Gleitkommazahlen. Für Beträge jenseits von Number.MAX_SAFE_INTEGER oder für exakte Dezimalwerte übergib bigint oder einen String.
Nicht zurückparsen: Die Ausgabe ist nur für die Anzeige gedacht. Es gibt keine eingebaute Umkehrfunktion. Speichere und übertrage Zahlen roh.
Kompatibilität: Grundfunktion und bigint werden von allen modernen Browsern und Node.js unterstützt. Die exakte Verarbeitung von Strings und Optionen wie roundingMode stammen aus NumberFormat v3 (ES2023) und fehlen in älteren Umgebungen. Dort werden Strings stattdessen in number umgewandelt.
Ausgabe je nach Engine: Die genaue Ausgabe hängt von den CLDR-Daten der jeweiligen Engine ab und kann sich zwischen Versionen leicht unterscheiden.

Siehe auch

Intl.NumberFormat Intl.NumberFormat.prototype.formatToParts() Intl.NumberFormat.prototype.formatRange() Intl.NumberFormat.prototype.resolvedOptions() Number.prototype.toLocaleString() Intl.DateTimeFormat.prototype.format()