JavaScript Reference: Number

This article explains how to work with JavaScript Number values and the built-in Number object.

JavaScript Numbers use the IEEE 754 binary64 format. The same type represents integers, fractions, Infinity, -Infinity, and NaN.

The exact rules are defined in the ECMAScript Number specification.

Create a Number value

The usual way is a number literal:

const age = 36
typeof age // 'number'

You can call Number() to convert another value:

Number('36') // 36
Number('') // 0
Number(true) // 1
Number('hello') // NaN

Number() follows JavaScript’s numeric conversion rules, which can sometimes be surprising. Validate input instead of assuming every conversion succeeded.

Avoid new Number()

Adding new creates a wrapper object, not a Number primitive:

const age = new Number(36)

typeof age // 'object'
age.valueOf() // 36

Wrapper objects behave differently in comparisons and conditionals:

new Number(0) === 0 // false
Boolean(new Number(0)) // true

Use Number primitives unless you have a very unusual reason to create a wrapper object.

Static properties

The Number constructor provides these constants:

• Number.EPSILON is the difference between 1 and the smallest Number greater than 1
• Number.MAX_SAFE_INTEGER is 2 ** 53 - 1, the largest safe integer
• Number.MIN_SAFE_INTEGER is -(2 ** 53 - 1), the smallest safe integer
• Number.MAX_VALUE is the largest positive finite Number
• Number.MIN_VALUE is the smallest positive nonzero Number, not the most negative Number
• Number.NaN is the special not-a-number value
• Number.NEGATIVE_INFINITY is negative infinity
• Number.POSITIVE_INFINITY is positive infinity

Their values are:

Number.EPSILON // 2.220446049250313e-16
Number.MAX_SAFE_INTEGER // 9007199254740991
Number.MIN_SAFE_INTEGER // -9007199254740991
Number.MAX_VALUE // 1.7976931348623157e+308
Number.MIN_VALUE // 5e-324
Number.NaN // NaN
Number.NEGATIVE_INFINITY // -Infinity
Number.POSITIVE_INFINITY // Infinity

Number.EPSILON is not the spacing between every pair of Numbers. Floating-point spacing grows with the magnitude of the values.

Static methods

These methods test or parse a value:

• Number.isNaN(value) returns true only when value is the Number value NaN; it does not coerce
• Number.isFinite(value) returns true only for a finite Number; it does not coerce
• Number.isInteger(value) returns true when the value is a Number with no fractional part
• Number.isSafeInteger(value) returns true when the value is an exactly represented integer in the safe range
• Number.parseFloat(value) parses a decimal Number from the beginning of a string
• Number.parseInt(value, radix) parses an integer from the beginning of a string using the requested base

Examples:

Number.isNaN(NaN) // true
Number.isNaN('hello') // false
Number.isFinite(10) // true
Number.isFinite('10') // false
Number.isInteger(10.0) // true
Number.isSafeInteger(9007199254740991) // true
Number.parseFloat('12.5px') // 12.5
Number.parseInt('101', 2) // 5

Number.parseFloat() and Number.parseInt() can return NaN, so check the result when parsing untrusted input.

What is a safe integer?

A safe integer is an integer that is exactly represented and does not share its Number representation with another integer.

The safe range is:

-(2 ** 53 - 1) through 2 ** 53 - 1

Outside that range, some integers are exactly representable and others are not. You cannot assume that consecutive mathematical integers remain distinguishable:

Number.MAX_SAFE_INTEGER + 1 === Number.MAX_SAFE_INTEGER + 2
// true

Use Number.isSafeInteger() before relying on exact integer behavior.

Use BigInt for larger integers

When you need arbitrary-size integer arithmetic, use BigInt:

const count = 9007199254740993n
const next = count + 1n

next // 9007199254740994n

BigInt is a separate primitive type. You cannot mix a BigInt and a Number directly in arithmetic:

1n + 1 // TypeError

Convert deliberately when needed, and remember that converting a large BigInt to Number can lose precision.

Number prototype methods

Number primitives can use the methods on Number.prototype. JavaScript temporarily boxes the primitive for the method call, so you do not need new Number().

const price = 12.5

price.toFixed(2) // '12.50'

The main methods are:

• .toExponential() returns a string in exponential notation
• .toFixed() returns a fixed-point string with the requested number of fractional digits
• .toLocaleString() formats the value using locale-sensitive conventions
• .toPrecision() returns a string with the requested number of significant digits
• .toString() returns a string, optionally using a radix from 2 through 36
• .valueOf() returns the Number primitive stored by a wrapper object

Examples:

const value = 1234.567

value.toExponential(2) // '1.23e+3'
value.toFixed(2) // '1234.57'
value.toPrecision(4) // '1235'
value.toString(16) // '4d2.9126e978d5'
value.toLocaleString('it-IT') // output depends on the runtime locale data

All formatting methods return strings. They do not change the original Number.

Related posts about js: