Skip to content

Numeric separators: readable number literals (ES2021)

  • How to group digits with _ in decimal, binary, octal, hexadecimal and BigInt literals.
  • The placement rules, and the syntax errors you get when you break them.
  • Why separators work only in source code, not in strings you parse at run time.
  • What TypeScript and older targets do with them.

TL;DR: since ECMAScript 2021 you can put a single underscore between any two digits of a numeric literal: 1_000_000, 0xFF_FF, 1_000n. The underscore is pure syntax. It does not change the value and it does not survive into strings, so String(1_000) is "1000" and Number("1_000") is NaN.

Long literals are hard to read and easy to get wrong. Is 100000000 ten million or one hundred million? In money code a missing zero is a hundredfold mistake, and in a code review nobody counts zeros reliably.

Running the samples: save a sample as a .mjs file and run it with Node.js 22 (node sample.mjs), or paste it into a browser console. All outputs shown were produced with Node.js 22.23.

// Before: count the zeros.
const maxOrderCentsOld = 100000000;
// ES2021: group digits however the reader expects.
const maxOrderCents = 100_000_000;
console.log(maxOrderCentsOld === maxOrderCents, maxOrderCents);
console.log(1_000.50); // decimal fraction
console.log(1e1_0); // exponent digits
console.log(0xFF_FF_FF); // hex, grouped by byte
console.log(0b1010_0001); // binary, grouped by nibble
console.log(0o7_5_5); // octal
console.log(9_007_199_254_740_993n); // BigInt
console.log(String(1_000_000)); // the separator is not part of the value

Output:

true 100000000
1000.5
10000000000
16777215
161
493
9007199254740993n
1000000

The specification adds one token, NumericLiteralSeparator :: _, to the numeric literal grammar. It may appear only between two digits. That gives four rules:

  • Not at the start or end of a literal, and not next to ., e, the 0x/0b/0o prefix or the BigInt n.
  • Not twice in a row.
  • Not after a leading 0 in a decimal literal (0_1), because that is the start of a legacy octal-like literal, which never accepts separators.
  • Any group size is allowed. The language does not check that you grouped by thousands.

Each broken rule is an early SyntaxError, so the whole script fails to load:

Source Result (V8 message)
1__000 SyntaxError: Only one underscore is allowed as numeric separator
1000_ SyntaxError: Numeric separators are not allowed at the end of numeric literals
1_.5, 1_n SyntaxError: Numeric separators are not allowed at the end of numeric literals
1._5, 1e_5, 0x_FF SyntaxError: Invalid or unexpected token
0_1 SyntaxError: Numeric separator can not be used after leading 0.
_1000 not a number at all: an identifier, so ReferenceError: _1000 is not defined

Messages are V8’s wording; other engines word them differently.

Separators belong to the lexical grammar of literals. The string-to-number conversion used by Number(), unary +, parseInt and parseFloat has its own grammar, and the specification explicitly says it cannot include a separator. JSON does not allow them either.

// Separators exist only in source code literals, not in strings that are parsed at run time.
console.log(Number('1_000'));
console.log(parseInt('1_000', 10));
console.log(parseFloat('3.14_15'));
console.log(JSON.parse('{"limit": 1000}').limit);
try {
JSON.parse('{"limit": 1_000}');
} catch (e) {
console.log(e.constructor.name);
}
console.log(BigInt('1_000'.replaceAll('_', '')));

Output:

NaN
1
3.14
1000
SyntaxError
1000n

parseInt and parseFloat are the dangerous ones: they stop at the underscore and return a wrong number instead of NaN. If configuration files or environment variables allow underscores for readability, strip them explicitly and validate the result.

OrdersPortal keeps its limits in one module. Grouping makes each value checkable at a glance, and binary flags show their bit positions:

// orders-config.mjs - OrdersPortal limits, written so a reviewer can check them at a glance.
export const LIMITS = Object.freeze({
maxOrderCents: 2_500_000_00, // $2,500,000.00 stored in cents: grouped as dollars_cents
requestTimeoutMs: 30_000, // 30 seconds
sessionTtlMs: 8 * 60 * 60 * 1_000, // 8 hours
maxUploadBytes: 25 * 1_024 * 1_024, // 25 MiB
largestOrderId: 9_007_199_254_740_991, // Number.MAX_SAFE_INTEGER
});
// Bit flags read better grouped by nibble.
export const Permission = Object.freeze({
READ: 0b0000_0001,
WRITE: 0b0000_0010,
REFUND: 0b0000_0100,
ADMIN: 0b1000_0000,
});
const support = Permission.READ | Permission.REFUND;
console.log(LIMITS);
console.log((support & Permission.REFUND) !== 0, (support & Permission.ADMIN) !== 0);
console.log(LIMITS.largestOrderId === Number.MAX_SAFE_INTEGER);
// Readability does not add precision: this literal is above the safe-integer range.
console.log(9_007_199_254_740_993, 9_007_199_254_740_993n);

Output:

{
maxOrderCents: 250000000,
requestTimeoutMs: 30000,
sessionTtlMs: 28800000,
maxUploadBytes: 26214400,
largestOrderId: 9007199254740991
}
true false
true
9007199254740992 9007199254740993n

Two points from this example. Grouping can carry meaning, as in 2_500_000_00 for dollars and cents, but unusual groups surprise readers, so add a comment. And separators make a literal readable, not precise: the last Number literal silently rounds to ...992. Use BigInt for integers beyond Number.MAX_SAFE_INTEGER.

  • Expecting Number() or parseInt() to accept them. Number('1_000') is NaN; parseInt('1_000') is 1. Separators are for source code only.
  • Misleading groups. 1_00_000 (the Indian lakh grouping) is valid and equals 100000. Any grouping is legal, so a wrong one passes silently. Agree on a convention and enforce it with a linter.
  • Separators in property keys. { 1_000: 'a' } creates the key "1000", as with any numeric literal key.
  • Mistaking _1000 for a number. A leading underscore makes an identifier, which usually fails with a ReferenceError far from the typo.
  • Old parsers. Tools that parse JavaScript with an old grammar (an outdated bundler, minifier or template engine) reject the syntax. Upgrade the tool or let a compiler downlevel it.

Use separators for long constants: money in cents, byte sizes, timeouts, large IDs, and bit masks in binary or hex. Skip them for short numbers where they add noise (1_0), and do not add them to data formats, environment variables or user input unless you strip them yourself. For computed values, writing the arithmetic (8 * 60 * 60 * 1_000) is often clearer than one long literal.

According to MDN’s browser compatibility data, numeric separators are supported in Chrome 75, Edge 79, Firefox 70, Safari 13 (including iOS), Node.js 12.5.0, Deno 1.2 and Bun 1.0. Internet Explorer never supported them. Because this is syntax, a polyfill is impossible: an unsupported engine fails to parse the whole file.

TypeScript and Babel: TypeScript accepts the syntax and removes it when compiling to a target older than ES2021. With TypeScript 6.0.3, --target es2020 turns 1_000_000 into 1000000 and 0b1111_0000 into 240, while --target es2021 keeps the source as written. Babel’s preset-env does the same for older targets.

1. Does 1_000 === 1000? Yes. The separator exists only in source text; the literal’s value is the same number, and String(1_000) is "1000".

2. What do Number('1_000') and parseInt('1_000') return? NaN and 1. The string numeric grammar used at run time does not include separators, and parseInt stops at the first character it cannot parse.

3. Where is an underscore not allowed in a numeric literal? At the start or end, twice in a row, next to a decimal point, exponent marker, radix prefix or n suffix, and after a leading 0 in a decimal literal.

4. Senior scenario: OrdersPortal reads limits such as MAX_ORDER_CENTS=2_500_000_00 from environment variables because operators like the readability. What do you need to watch for? The runtime parser does not understand separators: Number() returns NaN and parseInt returns 2, a silently wrong limit. Write one config loader that strips underscores, parses with Number, and rejects anything that is not a safe integer in the expected range. Fail at startup rather than at the first large order, and log the parsed value.

  • Numeric separators (ES2021) let you group digits with _ in every kind of numeric literal, including BigInt.
  • They are only allowed between two digits; misuse is a SyntaxError at parse time.
  • They do not affect the value, its string form or its precision.
  • Runtime parsing (Number, parseInt, parseFloat, JSON) does not accept them.