JavaScript BigInt toLocaleString() Method

Beginner
6 min read
Updated: Nov 2026
3 examples
Instance method

Definition

toLocaleString() turns a BigInt into human-friendly text for a given language and region, called a locale (for example "en-US" or "de-DE"). It adds the right thousands separators, and with options it can show currency, compact forms like 1.2M, or decimal places. It uses the same rules as Intl.NumberFormat. Unlike a normal Number, a BigInt is formatted exactly: all 22 digits of 1234567890123456789012n appear, with no rounding to zeros.

Remember
const big = 1234567n;
big.toLocaleString("en-US");                       // "1,234,567"
big.toLocaleString("de-DE");                       // "1.234.567"
big.toLocaleString("en-IN");                       // "12,34,567"
big.toLocaleString("en-US", { notation: "compact" });               // "1.2M"
big.toLocaleString("en-US", { style: "currency", currency: "USD" });  // "$1,234,567.00"

Syntax

Call it on a BigInt value. Both arguments are optional, but pass a locale whenever the output must look the same on every computer.

JavaScript
bigint.toLocaleString()
bigint.toLocaleString(locales)
bigint.toLocaleString(locales, options)
CallWhat it does
big.toLocaleString("en-US")Groups digits in threes with commas: 1,234,567.
big.toLocaleString("en-IN")Uses Indian grouping (lakh and crore): the last three digits, then pairs, as in 12,34,567.
big.toLocaleString("en-US", { style: "currency", currency: "USD" })Adds a currency symbol and two decimal places: $1,234,567.00.
big.toLocaleString("en-US", { notation: "compact" })Shortens the number for dashboards: 1.2M.
big.toLocaleString()Uses the default locale of the browser or computer, so the same code can print 1,234,567 on one machine and 1.234.567 on another.

Part of BigInt since ES2020. Locale data comes from the Internationalization API (Intl), which every modern browser and Node.js ship with. For many numbers in one format, create one Intl.NumberFormat and call its format() method: it accepts BigInts too and gives the same text.

Library declarations
JavaScript
bigint.toLocaleString(locales, options)   // returns a string

// locales: a language tag such as "en-US", or an array of tags (optional)
// options: the Intl.NumberFormat options (optional), for example
//          style, currency, notation, compactDisplay,
//          minimumFractionDigits, maximumFractionDigits, useGrouping

Parameters

ParameterDescription
localesOptional. A language tag such as "en-US", "de-DE", "en-IN", or "ja-JP", or an array of tags to try in order. Leave it out and the user’s or system’s locale is used, so output differs between machines. A malformed tag throws a RangeError.
optionsOptional. An object with formatting choices: style ("decimal", "currency", "percent", "unit"), currency (required when style is currency), notation (for example "compact"), minimumFractionDigits, useGrouping, and more.

Return Value

Return ValueDescription
StringThe formatted text. It is a string, not a number, so use it only for display; keep the BigInt for any further math.

JavaScript Examples

Example 1 — Group a 22-Digit Number Without Losing Digits

A Number can only keep about 16 significant digits, so formatting a huge Number shows made-up zeros. A BigInt keeps every digit.

JavaScript
const grains = 1234567890123456789012n;

console.log(grains.toString());                        // 1234567890123456789012
console.log(grains.toLocaleString("en-US"));           // 1,234,567,890,123,456,789,012
console.log(Number(grains).toLocaleString("en-US"));   // 1,234,567,890,123,456,800,000
Try It Yourself

How It Works

  1. toString() gives raw digits. Without formatting, the 22 digits are hard to read, but they are all correct.
  2. toLocaleString("en-US") adds commas. The BigInt is grouped in threes and every digit stays exact, right down to the final 012.
  3. The Number version is rounded. Converting to a Number first keeps only about 16 significant digits, so the end turns into 800,000. Format the BigInt directly to avoid that.

Example 2 — The Same Number in Four Locales

Different countries group digits differently. Loop over four locale tags and format one view count for each.

JavaScript
const views = 123456789n;
const locales = ["en-US", "de-DE", "en-IN", "ja-JP"];

locales.forEach(function (locale) {
  console.log(locale + ": " + views.toLocaleString(locale));
});
Try It Yourself

The page always passes a locale on purpose. Calling views.toLocaleString() with no arguments uses your own browser or system locale, so its output depends on who runs it.

How It Works

  1. US English and Japanese use commas. "en-US" and "ja-JP" both group by three with a comma: 123,456,789.
  2. German uses dots. In "de-DE" the dot is the group separator (and the comma is the decimal mark), giving 123.456.789.
  3. Indian English groups in lakhs. "en-IN" keeps the last three digits together and then groups by two: 12,34,56,789 (12 crore, 34 lakh, ...).

Example 3 — Currency, Compact Numbers, and Other Options

The second argument takes the same options as Intl.NumberFormat. Here one revenue value is shown five ways.

JavaScript
const revenue = 1234567n;

console.log(revenue.toLocaleString("en-US", { style: "currency", currency: "USD" }));
console.log(revenue.toLocaleString("en-US", { notation: "compact" }));
console.log(revenue.toLocaleString("en-US", { notation: "compact", compactDisplay: "long" }));
console.log(revenue.toLocaleString("en-US", { minimumFractionDigits: 2 }));
console.log(revenue.toLocaleString("en-US", { useGrouping: false }));
Try It Yourself

How It Works

  1. Currency adds the symbol and cents. With style: "currency" and currency: "USD", the BigInt is shown as dollars with two decimal places. Leaving out currency throws a TypeError.
  2. Compact notation shortens it. notation: "compact" gives 1.2M; adding compactDisplay: "long" spells it out as 1.2 million.
  3. Fine-tune decimals and grouping. minimumFractionDigits: 2 appends .00, and useGrouping: false removes the commas while still returning a string.

Browser & Runtime Support

BigInt.prototype.toLocaleString() arrived in ES2020. Its locale and option support comes from the built-in Intl API.

✓ Baseline · ES2020 + Intl

BigInt.prototype.toLocaleString()

Works in all modern browsers and in Node.js, Deno, and Bun. Common locales such as en-US, de-DE, en-IN, and ja-JP format the same way everywhere, because engines share the same Unicode CLDR locale data.

95% Modern browser support
Google Chrome Modern versions · uses the built-in locale data
Full support
Mozilla Firefox Modern versions · uses the built-in locale data
Full support
Apple Safari Modern versions · uses the built-in locale data
Full support
Microsoft Edge Modern versions · uses the built-in locale data
Full support
Opera Modern versions · uses the built-in locale data
Full support
Samsung Internet Modern versions · uses the built-in locale data
Full support
Internet Explorer No BigInt type
Not supported
Node.js Current releases ship full ICU · checked on Node 24
Supported
Deno Current releases
Supported
Bun Current releases
Supported
BigInt.prototype.toLocaleString() Excellent

Bottom line: Safe to use. Output for rare locales or new options can differ slightly between engine versions, because locale data is updated over time. Node.js builds that ship without full locale data (rare custom builds) may fall back to English formatting.

Frequently Asked Questions

Call big.toLocaleString("en-US"). For 1234567n it returns the string "1,234,567". Pass the locale explicitly so the result is the same on every computer.
Without a locale argument it uses the default locale of the browser or operating system. A German system prints 1.234.567 and a US system prints 1,234,567. Pass a locale such as "en-US" to fix the format.
Yes. Use options such as { style: "currency", currency: "USD" }. For 1234567n in "en-US" that gives "$1,234,567.00". The currency option is required with the currency style.
Yes. It formats every digit of the BigInt. Converting to a Number first would round anything above about 16 significant digits.
They produce the same text. toLocaleString() is handy for one value; new Intl.NumberFormat(locale, options) creates a reusable formatter that is faster when you format many values.

Next: toString()

Turn a BigInt into plain text in any base from 2 to 36, including hex and binary.

toString() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

11 people found this page helpful