Numeric separators: readable number literals (ES2021)
What you’ll learn
Section titled “What you’ll learn”- 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.
Summary
Section titled “Summary”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.
The problem it solves
Section titled “The problem it solves”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 fractionconsole.log(1e1_0); // exponent digitsconsole.log(0xFF_FF_FF); // hex, grouped by byteconsole.log(0b1010_0001); // binary, grouped by nibbleconsole.log(0o7_5_5); // octalconsole.log(9_007_199_254_740_993n); // BigIntconsole.log(String(1_000_000)); // the separator is not part of the valueOutput:
true 1000000001000.510000000000167772151614939007199254740993n1000000How it works
Section titled “How it works”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, the0x/0b/0oprefix or the BigIntn. - Not twice in a row.
- Not after a leading
0in 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.
Only in source code
Section titled “Only in source code”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:
NaN13.141000SyntaxError1000nparseInt 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.
Realistic example
Section titled “Realistic example”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 falsetrue9007199254740992 9007199254740993nTwo 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.
Common mistakes
Section titled “Common mistakes”- Expecting
Number()orparseInt()to accept them.Number('1_000')isNaN;parseInt('1_000')is1. Separators are for source code only. - Misleading groups.
1_00_000(the Indian lakh grouping) is valid and equals100000. 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
_1000for a number. A leading underscore makes an identifier, which usually fails with aReferenceErrorfar 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.
When to use it and when not to
Section titled “When to use it and when not to”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.
Compatibility
Section titled “Compatibility”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.
Interview questions
Section titled “Interview questions”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.
Key takeaways
Section titled “Key takeaways”- 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
SyntaxErrorat parse time. - They do not affect the value, its string form or its precision.
- Runtime parsing (
Number,parseInt,parseFloat, JSON) does not accept them.
Related pages
Section titled “Related pages”- Octal and Binary Literals: the
0band0oliterals that benefit most from grouping. - BigInt: integers beyond
Number.MAX_SAFE_INTEGER, with separators too. - Exponentiation Operator:
10 ** 6as an alternative way to write large constants. - JavaScript math: numbers and arithmetic basics.
Official references
Section titled “Official references”- ECMAScript Language Specification, Numeric Literals (current draft; separators first published in ECMAScript 2021)
- ECMAScript Language Specification,
StringToNumber - ECMAScript 2021 Language Specification (ECMA-262, 12th edition)
- TC39 proposal: Numeric separators
- MDN: Lexical grammar, numeric separators